Skip to main content

What is a Policy Rule?

A Policy Rule is a condition → actions pair. When the input facts satisfy the condition, the rule’s actions fire. Rules are evaluated in priority order — 1 is the highest. Within a version, priorities always form a contiguous 1…N sequence: new rules are appended at the end, and reordering rewrites the whole sequence.
Each rule belongs to a specific policy version and has a name, a priority, a condition (tree-structured logic), and one or more actions.

Condition Syntax

Conditions use a tree structure with two node types: SINGLE and GROUP.
LexQ conditions use type: "SINGLE" / type: "GROUP", field, operator, value, and valueType fields. Always use this format when calling the API or CLI.

SINGLE Condition

A leaf node that compares a single fact against a value:

GROUP Condition

A branch node that combines child conditions with AND or OR:

Operators

For IN / NOT_IN, the Compatible Types column refers to the type of the fact being checked (STRING or NUMBER). The value you provide is the list itself — its valueType is LIST_STRING or LIST_NUMBER.
Do not use CONTAINS on a list fact. CONTAINS is substring matching on a STRING. For LIST_STRING / LIST_NUMBER facts use HAS_ANY / HAS_ALL / HAS_NONE, and send the value as an array (["electronics"]), not a comma-joined string.IN / NOT_IN are the mirror image: a scalar fact checked against a list value. HAS_* are list-on-both-sides.

Value Types

A value you write in a rule’s condition or action has the same value limits as a value in an execution call. Saving or publishing a rule with a value over a limit fails with 400 (P-064), and the message gives the value’s path.

Nested Conditions Example

(customerTier = "VIP" AND paymentAmount >= 100000) OR region IN ["KR", "JP"]
In the example above, customerTier, region, and paymentAmount are custom facts that should be registered in Fact Definitions. A key that a rule only reads can be referenced before you register it — LexQ flags any unregistered key with a non-blocking warning rather than rejecting the rule — but registering enables type validation and value domains. An action target must be registered first (see Action Types). Some facts are pre-registered for every tenant (see Pre-registered Facts).

Action Types

LexQ engine actions are domain-agnostic primitives. The engine sees only numbers and structures — it does not assume commerce, fintech, insurance, or any specific business model. Domain-specific semantics live in your fact names. The engine never calls external systems. It mutates facts and records decisions; your caller reads the response and acts on it. The targetVar of SET_FACT and MUTATE_FACT must be a registered fact. Saving or publishing a rule whose action writes to an unregistered key fails with ACT-032, so register it in Fact Definitions first. Only BLOCK writes isBlocked and blockReason. Saving or publishing a rule whose SET_FACT or MUTATE_FACT targets either key fails with ACT-033, even though both are registered. Actions must also use facts in the data types they are registered with. The targetVar of a MUTATE_FACT must be a NUMBER fact, and so must its refVar if the refVar is a registered fact. If either is not a NUMBER fact, saving or publishing the rule fails with ACT-035. If the value of a SET_FACT does not match the data type of its targetVar, saving or publishing the rule fails with ACT-036. For example, "10" does not match a NUMBER fact. A null value matches a fact of any data type. Saving an edited rule checks every action in the rule again, including actions you did not change. The save can fail because of an action you did not touch. Fix the action that the error names, then save again.

MUTATE_FACT parameters

operator × method matrix DIV + AMOUNT requires operand ≠ 0. In every combination, operand is read as a number. Saving or publishing the rule fails with ACT-030 when operand is missing, null, or blank, and with C-005 when it does not read as a number, such as "ten" or true.
targetVar must be present in the request facts as a number. A missing fact throws — the engine never defaults to 0. Accumulation scenarios must send a starting value (pointsEarned: 0); the engine is stateless and does not read your database.Writing a key the request did not send is SET_FACT’s job.

When targetVar and refVar differ

refVar is only meaningful in PERCENTAGE × . Specifying it in any other cell is an error, not a silent no-op — AMOUNT has no base concept, and MUL × PERCENTAGE is a multiplier shorthand that reads no base. Use it when the base differs from the target:
loyaltyPoint += orderTotal × 5% — two different facts. Omitting refVar would compute loyaltyPoint += loyaltyPoint × 5% instead.
Ranges are not constrained. Negative operands and percentages above 100 are valid — refunds (-5), surcharges (150), risk scores, and game points all need them. Range validation belongs in your fact definitions, not the engine — declare a value domain with min and max on the fact itself.That constrains the input a caller sends, not what an action computes. A MUTATE_FACT may still take paymentAmount outside the declared range; that outcome belongs to a Dry Run.

MUTATE_FACT — Percentage

Reduce paymentAmount by 10%. Currency facts should also set rounding — see below.

MUTATE_FACT — Fixed Amount

MUTATE_FACT — With Rounding

Without rounding, a result keeps at most 34 significant digits and at most 34 digits after the decimal point. Extra digits are rounded half-even. For example, 7 ÷ 90 gives 0.0777777777777777777777777777777778. A calculated number is within the value limits, so sending it back unchanged in a later request does not fail with P-064. Specify rounding when you need currency-scale output. If a result, or the __delta of the changed fact, has more than 34 digits before the decimal point, the call fails with 400 (ACT-034). Send smaller values or change the calculation. In an organization that uses Fail-open, an action whose result has too many digits is skipped instead, and the call continues. A __delta with too many digits still fails the call.
mode accepts UP, DOWN, CEILING, FLOOR, HALF_UP, HALF_DOWN, HALF_EVEN. Defaults to HALF_UP.

SET_FACT — Assign a value

Assigns a literal of any type. This is the only action that can write a key the request did not send. The targetVar still has to be a registered fact.
SET_FACT assigns rather than appends. To accumulate into a LIST_STRING fact, send the current list in the request and assign the full new list. Because it is an assignment and not an arithmetic change, SET_FACT produces no __delta. If a MUTATE_FACT also changes the same fact, its __delta includes the SET_FACT change (see How a request runs).

BLOCK — Record a rejection

BLOCK does not halt execution. Subsequent actions in the same rule and subsequent winning rules still run. It writes two facts, isBlocked (true) and blockReason (the reason, or Policy Violation if it is omitted); enforcement is your caller’s responsibility. No condition sees these values within the same request.

How a request runs

A request runs in two steps:
  1. Every rule’s condition is checked against the facts in the request. This happens before any action runs, so a condition never sees a value that an action writes during the same request.
  2. The actions of the matching rules run in priority order. Each action works on the values left by the actions before it, including actions in earlier rules.
For example, a request sends customerTier: "STAFF" and paymentAmount: 100, and two rules match: Rule 2 still matches, because its condition sees the request value 100, not 20. Its action multiplies the 20 that rule 1 left. The response has mutatedFacts.paymentAmount = 60 and generatedVariables.paymentAmount__delta = -40. The delta compares the final value with the request value, so it includes the SET_FACT change. If both rules are in the same EXCLUSIVE mutex group, only rule 1 fires and the result is 20. When a later decision has to depend on an earlier result, call the API again with that result, or put both actions in one rule.

Generated Variables

In addition to the mutated facts, the engine exposes per-action change information in generatedVariables: When several actions change the same fact, in one rule or across rules, __delta reports the total change from the request value. Per-action snapshots are available in executionTraces for audit drill-down.

Mutex — Rule-Level Conflict Resolution

Within a single version, rules can belong to a mutex group to control how many matching rules fire. When mutexMode is EXCLUSIVE, only the single winning rule fires. When it is MAX_N, up to mutexLimit rules fire in priority order. Other matching rules in the same mutex group are skipped and logged in the Decision Trace with status BLOCKED and reason MUTEX_PRIORITY_LOST or MUTEX_LIMIT_REACHED (see Decision Trace).

When an input is null

A condition on a null value does not match, and rules that block a request are no exception. For example, if the risk model returns no score and the request sends paymentRiskScore as null, a rule that blocks transfers scored 75 or higher (paymentRiskScore >= 75) does not match it. If the group has only blocking rules, none of them fires for that transfer, so it gets no BLOCK. Here, null means a key sent with the value null. A request that leaves the key out fails with P-015 before any rule runs. To make sure a request with a null input still gets a decision, sort the rules into three kinds (risk rules, an approval rule, and a default hold) and put them in one mutex group with mode EXCLUSIVE and strategy HIGHEST_PRIORITY. Only the matching rule with the lowest priority number fires. Fintech: Transfer Approval is built this way: In this template, a transfer whose paymentRiskScore is null does not match the approval rule (10). If no risk rule (1 to 9) matches either, the default hold (11) fires: it sets transferDecision to REVIEW and adds a BLOCK with the reason INPUT_MISSING. To set this up in your own group:
  1. Give priority 1 to the rule with the strictest decision.
  2. Put an approval rule right above the default hold. In its condition, add one check per input that the other rules in the group read, and join the checks with AND. The table below shows a check for each type.
  3. Give the largest priority number in the group to a rule with an empty condition group, and give it the decision for requests that no rule above it matches.
The decision trace shows which rule fired.

Decision Trace

Every rule evaluation produces a decision trace entry explaining whether the rule fired and why. This is the core of LexQ’s audit-grade reasoning — every outcome can be traced back to a specific status and reason code. A decision trace entry has two classifying fields:
  • status — the high-level outcome category
  • reasonCode — the specific reason within that category

DecisionStatus

DecisionReasonCode

Status × ReasonCode Mapping

When debugging “why didn’t my rule fire?”, the decision trace gives you the answer in two steps: the status tells you which category of filtering removed the rule, and the reasonCode tells you exactly which check rejected it.
CONDITION_MISMATCH covers two different facts: the condition evaluated to false, and the condition could not be evaluated (type mismatch, unresolved fact). The specific cause is in reasonDetail — for example Evaluation error: FACT_TYPE_MISMATCH when a LIST_STRING fact receives a plain string. A rule that fails to evaluate does not stop the execution; the rest of the rules run normally.

Complete Rule Example

Register both action targets, paymentAmount and discountApplied, as facts before you save this rule.

Next Steps

Fact Definitions

Define the input variables your rules expect.

Dry Run

Test your rules before publishing.