Policy Rules

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.

IF condition matches → THEN execute actions

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 uses its own condition DTO format with type: "SINGLE" / type: "GROUP", field, operator, value, and valueType fields. Do not confuse this with the Console’s internal form representation which may use different field names. Always use the engine format when calling the API or CLI.

SINGLE Condition

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

{
  "type": "SINGLE",
  "field": "paymentAmount",
  "operator": "GREATER_THAN_OR_EQUAL",
  "value": 100000,
  "valueType": "NUMBER"
}

GROUP Condition

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

{
  "type": "GROUP",
  "operator": "AND",
  "children": [
    { "type": "SINGLE", "field": "customerTier", "operator": "EQUALS", "value": "VIP", "valueType": "STRING" },
    { "type": "SINGLE", "field": "paymentAmount", "operator": "GREATER_THAN", "value": 50000, "valueType": "NUMBER" }
  ]
}

Operators

Operator	Compatible Types	Description
`EQUALS`	All	Exact match
`NOT_EQUALS`	All	Negation
`GREATER_THAN`	NUMBER	`>`
`GREATER_THAN_OR_EQUAL`	NUMBER	`>=`
`LESS_THAN`	NUMBER	`<`
`LESS_THAN_OR_EQUAL`	NUMBER	`<=`
`CONTAINS`	STRING	Substring match
`IN`	STRING, NUMBER	Value is in the provided list
`NOT_IN`	STRING, NUMBER	Value is not in the provided list
`HAS_ANY`	LIST_STRING, LIST_NUMBER	The fact’s list shares at least one element with the value
`HAS_ALL`	LIST_STRING, LIST_NUMBER	The fact’s list contains every element of the value
`HAS_NONE`	LIST_STRING, LIST_NUMBER	The fact’s list shares no element with the value

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

Type	JSON Value	Example
`STRING`	`"string"`	`"VIP"`
`NUMBER`	`number`	`100000`
`BOOLEAN`	`true / false`	`true`
`LIST_STRING`	`["a", "b"]`	`["KR", "US"]`
`LIST_NUMBER`	`[1, 2]`	`[10000, 20000]`

Nested Conditions Example

(customerTier = "VIP" AND paymentAmount >= 100000) OR region IN ["KR", "JP"]

{
  "type": "GROUP",
  "operator": "OR",
  "children": [
    {
      "type": "GROUP",
      "operator": "AND",
      "children": [
        { "type": "SINGLE", "field": "customerTier", "operator": "EQUALS", "value": "VIP", "valueType": "STRING" },
        { "type": "SINGLE", "field": "paymentAmount", "operator": "GREATER_THAN_OR_EQUAL", "value": 100000, "valueType": "NUMBER" }
      ]
    },
    { "type": "SINGLE", "field": "region", "operator": "IN", "value": ["KR", "JP"], "valueType": "LIST_STRING" }
  ]
}

In the example above, customerTier, region, and paymentAmount are custom facts that should be registered in Fact Definitions. You can reference a fact before registering it — LexQ flags any unregistered key with a non-blocking warning rather than rejecting the rule — but registering enables type validation and Required Input Facts analysis. Only userId and userTags are system facts available by default.

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. This preserves audit-grade separation between engine state and external state.

Action Type	Description	Parameters
`MUTATE_FACT`	Change a numeric fact in place using an arithmetic operator	`targetVar`, `operator`, `method`, `operand`, `refVar` (optional), `rounding` (optional)
`SET_FACT`	Assign a literal value — creates the fact if absent	`targetVar`, `value`
`BLOCK`	Record a rejection decision	`reason`

MUTATE_FACT parameters

Parameter	Required	Meaning
`targetVar`	always	The fact this action reads and writes. Must already exist as a number at execution time.
`operator`	always	`ASSIGN` \| `ADD` \| `SUB` \| `MUL` \| `DIV`
`method`	always	`PERCENTAGE` \| `AMOUNT` — dictates the unit of `operand`
`operand`	always	The arithmetic operand. A percentage when `PERCENTAGE`, an absolute amount when `AMOUNT`.
`refVar`	optional	Base for percentage calculation. Omit to use `targetVar` itself.
`rounding`	optional	`{ "scale": 0–34, "mode": "HALF_UP" }`. Omit for lossless full precision.

operator × method matrix

Operator	`AMOUNT`	`PERCENTAGE`
`ASSIGN`	`targetVar = operand`	`targetVar = refVar × operand / 100`
`ADD`	`targetVar += operand`	`targetVar += refVar × operand / 100`
`SUB`	`targetVar -= operand`	`targetVar -= refVar × operand / 100`
`MUL`	`targetVar *= operand`	`targetVar *= (operand / 100 + 1)`
`DIV`	`targetVar /= operand`	invalid — use `MUL` with the inverse

DIV + AMOUNT requires operand ≠ 0.

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.Creating a fact from nothing 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:

{
  "type": "MUTATE_FACT",
  "parameters": {
    "targetVar": "loyaltyPoint",
    "refVar": "orderTotal",
    "operator": "ADD",
    "method": "PERCENTAGE",
    "operand": 5
  }
}

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.

MUTATE_FACT — Percentage

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

{
  "type": "MUTATE_FACT",
  "parameters": {
    "targetVar": "paymentAmount",
    "operator": "SUB",
    "method": "PERCENTAGE",
    "operand": 10
  }
}

MUTATE_FACT — Fixed Amount

{
  "type": "MUTATE_FACT",
  "parameters": {
    "targetVar": "paymentAmount",
    "operator": "SUB",
    "method": "AMOUNT",
    "operand": 5000
  }
}

MUTATE_FACT — With Rounding

Without rounding, the result is preserved at full precision. Specify it when you need currency-scale output.

{
  "type": "MUTATE_FACT",
  "parameters": {
    "targetVar": "paymentAmount",
    "operator": "SUB",
    "method": "PERCENTAGE",
    "operand": 13.7,
    "rounding": { "scale": 0, "mode": "HALF_UP" }
  }
}

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 creates a fact that did not exist.

{
  "type": "SET_FACT",
  "parameters": { "targetVar": "riskLevel", "value": "HIGH" }
}

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.

BLOCK — Record a rejection

{
  "type": "BLOCK",
  "parameters": { "reason": "Suspected fraud" }
}

BLOCK does not halt execution. Subsequent actions in the same rule and subsequent winning rules still run. It writes the isBlocked fact; enforcement is your caller’s responsibility.

Generated Variables

In addition to the mutated facts, the engine exposes per-action change information in generatedVariables:

Pattern	Meaning	Generated By
`{targetVar}__delta`	Net change to `targetVar` (`mutated − original`, signed)	`MUTATE_FACT`

When multiple actions in a rule mutate the same fact, __delta reports the cumulative change. 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.

Field	Description
`mutexGroup`	A string key grouping related rules (e.g., `"best-discount"`)
`mutexMode`	`NONE` (default), `EXCLUSIVE`, or `MAX_N`
`mutexStrategy`	`HIGHEST_PRIORITY` — the rule with the lowest priority number wins (1 is highest). Order is set by the author, not inferred from values. Currently the only strategy.
`mutexLimit`	Max number of rules to fire from this group (for `MAX_N`)

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).

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

Status	Meaning
`SELECTED`	The rule fired and its actions ran
`NO_MATCH`	The rule’s condition evaluated to false
`NOT_SELECTED`	Pre-competition filter (e.g., effective period — reserved for future)
`BLOCKED`	The rule lost mutex or execution group competition
`ERROR`	An action or engine error occurred during evaluation

DecisionReasonCode

ReasonCode	Meaning
`FINAL_WINNER`	The selected rule for this evaluation
`EFFECTIVE_DATE_INVALID`	Outside the rule’s effective period `[from, to]` (reserved)
`CONDITION_MISMATCH`	The rule’s condition tree did not match the input facts
`MUTEX_PRIORITY_LOST`	EXCLUSIVE mutex (limit=1) — another rule had a lower priority number
`MUTEX_LIMIT_REACHED`	MAX_N mutex (limit>1) — `mutexLimit` was filled by higher-priority rules
`GROUP_PRIORITY_LOST`	EXCLUSIVE execution group (limit=1) — another group won by priority
`GROUP_LIMIT_REACHED`	MAX_N execution group (limit>1) — `executionLimit` groups already won
`ACTION_ERROR`	An action executor threw during this rule’s execution
`ENGINE_ERROR`	The engine itself failed before/during this rule

Status × ReasonCode Mapping

Status	Possible ReasonCodes
`SELECTED`	`FINAL_WINNER`
`NO_MATCH`	`CONDITION_MISMATCH`
`NOT_SELECTED`	`EFFECTIVE_DATE_INVALID` (reserved)
`BLOCKED`	`MUTEX_PRIORITY_LOST`, `MUTEX_LIMIT_REACHED`, `GROUP_PRIORITY_LOST`, `GROUP_LIMIT_REACHED`
`ERROR`	`ACTION_ERROR`, `ENGINE_ERROR`

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

{
  "name": "VIP 20% Discount",
  "condition": {
    "type": "GROUP",
    "operator": "AND",
    "children": [
      { "type": "SINGLE", "field": "customerTier", "operator": "EQUALS", "value": "VIP", "valueType": "STRING" },
      { "type": "SINGLE", "field": "paymentAmount", "operator": "GREATER_THAN_OR_EQUAL", "value": 100000, "valueType": "NUMBER" }
    ]
  },
  "actions": [
    { "type": "MUTATE_FACT", "parameters": { "targetVar": "paymentAmount", "operator": "SUB", "method": "PERCENTAGE", "operand": 20, "rounding": { "mode": "HALF_UP", "scale": 2 } } },
    { "type": "SET_FACT", "parameters": { "targetVar": "discountApplied", "value": true } }
  ],
  "mutexGroup": "best-discount",
  "mutexMode": "EXCLUSIVE",
  "mutexStrategy": "HIGHEST_PRIORITY",
  "isEnabled": true
}

Getting Started

Core Concepts

Features

What is a Policy Rule?

Condition Syntax

SINGLE Condition

GROUP Condition

Operators

Value Types

Nested Conditions Example

Action Types

MUTATE_FACT parameters

When targetVar and refVar differ

MUTATE_FACT — Percentage

MUTATE_FACT — Fixed Amount

MUTATE_FACT — With Rounding

SET_FACT — Assign a value

BLOCK — Record a rejection

Generated Variables

Mutex — Rule-Level Conflict Resolution

Decision Trace

DecisionStatus

DecisionReasonCode

Status × ReasonCode Mapping

Complete Rule Example

Next Steps

Fact Definitions

Dry Run

​What is a Policy Rule?

​Condition Syntax

​SINGLE Condition

​GROUP Condition

​Operators

​Value Types

​Nested Conditions Example

​Action Types

​MUTATE_FACT parameters

​When targetVar and refVar differ

​MUTATE_FACT — Percentage

​MUTATE_FACT — Fixed Amount

​MUTATE_FACT — With Rounding

​SET_FACT — Assign a value

​BLOCK — Record a rejection

​Generated Variables

​Mutex — Rule-Level Conflict Resolution

​Decision Trace

​DecisionStatus

​DecisionReasonCode

​Status × ReasonCode Mapping

​Complete Rule Example

​Next Steps

Fact Definitions

Dry Run

What is a Policy Rule?

Condition Syntax

SINGLE Condition

GROUP Condition

Operators

Value Types

Nested Conditions Example

Action Types

MUTATE_FACT parameters

When targetVar and refVar differ

MUTATE_FACT — Percentage

MUTATE_FACT — Fixed Amount

MUTATE_FACT — With Rounding

SET_FACT — Assign a value

BLOCK — Record a rejection

Generated Variables

Mutex — Rule-Level Conflict Resolution

Decision Trace

DecisionStatus

DecisionReasonCode

Status × ReasonCode Mapping

Complete Rule Example

Next Steps