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 contiguous1…N sequence: new rules are appended at the end, and reordering rewrites the whole sequence.
Condition Syntax
Conditions use a tree structure with two node types:SINGLE and GROUP.
SINGLE Condition
A leaf node that compares a single fact against a value:GROUP Condition
A branch node that combines child conditions withAND 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.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.
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
ReducepaymentAmount by 10%. Currency facts should also set rounding — see below.
MUTATE_FACT — Fixed Amount
MUTATE_FACT — With Rounding
Withoutrounding, 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. ThetargetVar 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
How a request runs
A request runs in two steps:- 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.
- 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.
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 ingeneratedVariables:
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 anull 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:
- Give priority 1 to the rule with the strictest decision.
- 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. - 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 categoryreasonCode— 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
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.

