@lexq/cli 0.1.39 → 0.1.40

package/dist/index.js

@@ -933,9 +933,27 @@ ${data.length} total`);
               ]
             }'
 
-        Condition Operators:
-          EQUALS, NOT_EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUAL,
-          LESS_THAN, LESS_THAN_OR_EQUAL, CONTAINS, IN, NOT_IN
+        Condition Operators (by fact type):
+          STRING        EQUALS, NOT_EQUALS, CONTAINS, IN, NOT_IN
+          NUMBER        EQUALS, NOT_EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUAL,
+                        LESS_THAN, LESS_THAN_OR_EQUAL, IN, NOT_IN
+          BOOLEAN       EQUALS, NOT_EQUALS
+          LIST_STRING   HAS_ANY, HAS_ALL, HAS_NONE
+          LIST_NUMBER   HAS_ANY, HAS_ALL, HAS_NONE
+
+          Using an operator outside its fact type is rejected by the server.
+
+        List-typed facts (HAS_*) — the value is always an array:
+          HAS_ANY    fact has at least one of the given values
+          HAS_ALL    fact has all of the given values
+          HAS_NONE   fact has none of the given values
+
+          Example:
+            { "type": "SINGLE", "field": "user_tags", "operator": "HAS_ANY",
+              "value": ["VIP", "GOLD"], "valueType": "LIST_STRING" }
+
+          CONTAINS is substring match on STRING facts, not list membership.
+          IN is the mirror of HAS_*: scalar fact, list value.
 
         Action Types:
           MUTATE_FACT, INCREMENT_FACT, EMIT_EVENT, BLOCK, EMIT_NOTIFICATION, EMIT_WEBHOOK, SET_FACT, ADD_TAG
@@ -3712,8 +3730,23 @@ function registerRuleTools(server, callApi) {
         defined (non-blocking, version-wide) — use it to decide what to register.
 
         Condition: { type: "SINGLE", field, operator, value, valueType } or { type: "GROUP", operator: "AND"|"OR", children: [...] }
-        Operators: EQUALS, NOT_EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, CONTAINS, IN, NOT_IN
         Value types: STRING, NUMBER, BOOLEAN, LIST_STRING, LIST_NUMBER
+        
+        Operators are constrained by the LEFT fact's type (from lexq_facts_list). Using one outside
+        its type is rejected by the server — check the fact type before choosing an operator.
+        - STRING fact:       EQUALS, NOT_EQUALS, CONTAINS, IN, NOT_IN
+        - NUMBER fact:       EQUALS, NOT_EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, IN, NOT_IN
+        - BOOLEAN fact:      EQUALS, NOT_EQUALS
+        - LIST_* fact:       HAS_ANY, HAS_ALL, HAS_NONE (only these)
+
+        HAS_* query list-typed facts. Value is always an array whose element type matches the fact:
+        - HAS_ANY: fact has at least one of the given values
+        - HAS_ALL: fact has all of the given values
+        - HAS_NONE: fact has none of the given values
+        Example: { "type": "SINGLE", "field": "user_tags", "operator": "HAS_ANY", "value": ["VIP","GOLD"], "valueType": "LIST_STRING" }
+
+        Do NOT use CONTAINS on a list fact — CONTAINS is substring match on STRING facts only.
+        IN is the mirror of HAS_*: IN takes a scalar fact with a list value; HAS_* takes lists on both sides.
 
         Actions: [{ type, parameters }]
 
@@ -3722,14 +3755,14 @@ function registerRuleTools(server, callApi) {
         - INCREMENT_FACT: { targetVar: string, method: "PERCENTAGE"|"AMOUNT", refVar?: string (required when PERCENTAGE), rate?: number (when PERCENTAGE), value?: number (when AMOUNT), rounding?: RoundingOption } targetVar (accumulation target) must exist at execution; refVar (PERCENTAGE source) must exist when method is PERCENTAGE. Each is supplied as an input fact or written by a prior action in this rule — a missing required fact throws (no 0 default). Note: external system call (e.g. point system sync) is NOT a primitive responsibility. Compose [INCREMENT_FACT, EMIT_EVENT] chain instead.
         - EMIT_EVENT: { integrationId: uuid, eventPayload: object (Map<string,unknown>, ≥1 entry) } eventPayload is passed through to the integration provider as-is. Domain-specific keys (couponId, ticketId, etc.) are routed by the provider, not validated by the engine.
         - BLOCK: { reason: string }
-        - EMIT_NOTIFICATION: { integrationId: uuid, targetVar: string, notificationPayload: object (Map<string,unknown>, ≥1 entry) } targetVar identifies the recipient fact (e.g. phone_number / email / device_token). notificationPayload (channel, templateId, body, variables, etc.) is passed through to the provider.
+        - EMIT_NOTIFICATION: { integrationId: uuid, targetVar: string, notificationPayload: object (Map<string,unknown>, ≥1 entry) } targetVar identifies the recipient fact (e.g. phone_number / email / device_token) and is REQUIRED — the named fact must be present in the request or the action throws. (Contrast with ADD_TAG, where targetVar is an optional write target that is created if absent.)
         - EMIT_WEBHOOK: { url: string, method: "POST", payloadTemplate?: object } payloadTemplate is optional. Without it, all facts are sent as-is. With it, the object is sent as the HTTP body with {{variables}} replaced at execution time. Variables: {{fact.xxx}}, {{output.xxx}}, {{timestamp}}, {{ruleName}}, {{groupName}}, {{versionNo}}, {{xxx}} (shorthand).
           Platform examples:
             Slack: { "text": "Rule {{ruleName}} fired — {{fact.customer_tier}}" }
             Discord: { "content": "Rule {{ruleName}} fired — {{fact.customer_tier}}" }
             Generic: { "event": "rule_matched", "rule": "{{ruleName}}", "amount": "{{output.payment_amount}}" }
         - SET_FACT: { key: string, value: string|number|boolean }
-        - ADD_TAG: { tag: string, targetVar: string }
+        - ADD_TAG: { tag: string, targetVar?: string (defaults to "user_tags") } Appends tag to a LIST_STRING fact, creating it if absent. Adding an existing tag is a no-op (idempotent). Read tags back with HAS_ANY / HAS_ALL / HAS_NONE.
         
         RoundingOption (optional, MUTATE_FACT / INCREMENT_FACT only): { scale: integer (0..16), mode?: "HALF_UP"|"HALF_DOWN"|"HALF_EVEN"|"FLOOR"|"CEILING"|"DOWN"|"UP" } mode defaults to HALF_UP. When omitted, calculator output is preserved at full precision (lossless).
       `,

package/dist/mcp/register.js

@@ -323,8 +323,23 @@ function registerRuleTools(server, callApi) {
         defined (non-blocking, version-wide) — use it to decide what to register.
 
         Condition: { type: "SINGLE", field, operator, value, valueType } or { type: "GROUP", operator: "AND"|"OR", children: [...] }
-        Operators: EQUALS, NOT_EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, CONTAINS, IN, NOT_IN
         Value types: STRING, NUMBER, BOOLEAN, LIST_STRING, LIST_NUMBER
+        
+        Operators are constrained by the LEFT fact's type (from lexq_facts_list). Using one outside
+        its type is rejected by the server — check the fact type before choosing an operator.
+        - STRING fact:       EQUALS, NOT_EQUALS, CONTAINS, IN, NOT_IN
+        - NUMBER fact:       EQUALS, NOT_EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, IN, NOT_IN
+        - BOOLEAN fact:      EQUALS, NOT_EQUALS
+        - LIST_* fact:       HAS_ANY, HAS_ALL, HAS_NONE (only these)
+
+        HAS_* query list-typed facts. Value is always an array whose element type matches the fact:
+        - HAS_ANY: fact has at least one of the given values
+        - HAS_ALL: fact has all of the given values
+        - HAS_NONE: fact has none of the given values
+        Example: { "type": "SINGLE", "field": "user_tags", "operator": "HAS_ANY", "value": ["VIP","GOLD"], "valueType": "LIST_STRING" }
+
+        Do NOT use CONTAINS on a list fact — CONTAINS is substring match on STRING facts only.
+        IN is the mirror of HAS_*: IN takes a scalar fact with a list value; HAS_* takes lists on both sides.
 
         Actions: [{ type, parameters }]
 
@@ -333,14 +348,14 @@ function registerRuleTools(server, callApi) {
         - INCREMENT_FACT: { targetVar: string, method: "PERCENTAGE"|"AMOUNT", refVar?: string (required when PERCENTAGE), rate?: number (when PERCENTAGE), value?: number (when AMOUNT), rounding?: RoundingOption } targetVar (accumulation target) must exist at execution; refVar (PERCENTAGE source) must exist when method is PERCENTAGE. Each is supplied as an input fact or written by a prior action in this rule — a missing required fact throws (no 0 default). Note: external system call (e.g. point system sync) is NOT a primitive responsibility. Compose [INCREMENT_FACT, EMIT_EVENT] chain instead.
         - EMIT_EVENT: { integrationId: uuid, eventPayload: object (Map<string,unknown>, ≥1 entry) } eventPayload is passed through to the integration provider as-is. Domain-specific keys (couponId, ticketId, etc.) are routed by the provider, not validated by the engine.
         - BLOCK: { reason: string }
-        - EMIT_NOTIFICATION: { integrationId: uuid, targetVar: string, notificationPayload: object (Map<string,unknown>, ≥1 entry) } targetVar identifies the recipient fact (e.g. phone_number / email / device_token). notificationPayload (channel, templateId, body, variables, etc.) is passed through to the provider.
+        - EMIT_NOTIFICATION: { integrationId: uuid, targetVar: string, notificationPayload: object (Map<string,unknown>, ≥1 entry) } targetVar identifies the recipient fact (e.g. phone_number / email / device_token) and is REQUIRED — the named fact must be present in the request or the action throws. (Contrast with ADD_TAG, where targetVar is an optional write target that is created if absent.)
         - EMIT_WEBHOOK: { url: string, method: "POST", payloadTemplate?: object } payloadTemplate is optional. Without it, all facts are sent as-is. With it, the object is sent as the HTTP body with {{variables}} replaced at execution time. Variables: {{fact.xxx}}, {{output.xxx}}, {{timestamp}}, {{ruleName}}, {{groupName}}, {{versionNo}}, {{xxx}} (shorthand).
           Platform examples:
             Slack: { "text": "Rule {{ruleName}} fired — {{fact.customer_tier}}" }
             Discord: { "content": "Rule {{ruleName}} fired — {{fact.customer_tier}}" }
             Generic: { "event": "rule_matched", "rule": "{{ruleName}}", "amount": "{{output.payment_amount}}" }
         - SET_FACT: { key: string, value: string|number|boolean }
-        - ADD_TAG: { tag: string, targetVar: string }
+        - ADD_TAG: { tag: string, targetVar?: string (defaults to "user_tags") } Appends tag to a LIST_STRING fact, creating it if absent. Adding an existing tag is a no-op (idempotent). Read tags back with HAS_ANY / HAS_ALL / HAS_NONE.
         
         RoundingOption (optional, MUTATE_FACT / INCREMENT_FACT only): { scale: integer (0..16), mode?: "HALF_UP"|"HALF_DOWN"|"HALF_EVEN"|"FLOOR"|"CEILING"|"DOWN"|"UP" } mode defaults to HALF_UP. When omitted, calculator output is preserved at full precision (lossless).
       `,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lexq/cli",
-  "version": "0.1.39",
+  "version": "0.1.40",
   "description": "LexQ CLI — manage policies, simulate rules, and deploy from the terminal. Built for humans and AI agents.",
   "type": "module",
   "bin": {

package/skills/lexq-recipes/SKILL.md

@@ -256,7 +256,7 @@ lexq rules create --group-id <gid> --version-id <vid> --json '{
       "type": "EMIT_NOTIFICATION",
       "parameters": {
         "integrationId": "<notification-integration-uuid>",
-        "target": "user_id",
+        "targetVar": "user_id",
         "notificationPayload": {
           "channel": "PUSH",
           "templateId": "welcome_points"
@@ -502,4 +502,73 @@ lexq analytics simulation start --json '{
 
 # 6. If simulation passes, deploy
 lexq deploy live --group-id <gid> --version-id <newVid> --memo "Migration complete"
-```
+```
+
+---
+
+## Recipe 11: Tag-Based Segmentation
+
+**Goal:** Write tags in one rule, branch on them in another.
+
+`user_tags` is a `LIST_STRING` fact seeded automatically for every tenant. `ADD_TAG` appends to
+it; `HAS_ANY` / `HAS_ALL` / `HAS_NONE` read it.
+
+```bash
+# Tags are written by earlier rules (or supplied as input facts).
+lexq rules create --group-id <gid> --version-id <vid> --json '{
+  "name": "Tag High-Value Customers",
+  "condition": {
+    "type": "SINGLE", "field": "lifetime_value", "operator": "GREATER_THAN_OR_EQUAL",
+    "value": 1000000, "valueType": "NUMBER"
+  },
+  "actions": [
+    { "type": "ADD_TAG", "parameters": { "tag": "high_value" } }
+  ]
+}'
+
+# Branch on any one of several tags
+lexq rules create --group-id <gid> --version-id <vid> --json '{
+  "name": "Priority Support for VIP or High Value",
+  "condition": {
+    "type": "SINGLE", "field": "user_tags", "operator": "HAS_ANY",
+    "value": ["VIP", "high_value"], "valueType": "LIST_STRING"
+  },
+  "actions": [{ "type": "SET_FACT", "parameters": { "key": "support_tier", "value": "PRIORITY" } }]
+}'
+
+# Require every tag
+lexq rules create --group-id <gid> --version-id <vid> --json '{
+  "name": "Beta Feature for Verified VIP",
+  "condition": {
+    "type": "SINGLE", "field": "user_tags", "operator": "HAS_ALL",
+    "value": ["VIP", "verified"], "valueType": "LIST_STRING"
+  },
+  "actions": [{ "type": "SET_FACT", "parameters": { "key": "beta_enabled", "value": true } }]
+}'
+
+# Exclude tagged users
+lexq rules create --group-id <gid> --version-id <vid> --json '{
+  "name": "Promo Excludes Fraud Review",
+  "condition": {
+    "type": "SINGLE", "field": "user_tags", "operator": "HAS_NONE",
+    "value": ["fraud_review", "suspended"], "valueType": "LIST_STRING"
+  },
+  "actions": [{ "type": "MUTATE_FACT", "parameters": {
+    "refVar": "payment_amount", "method": "PERCENTAGE", "operator": "SUB", "rate": 5,
+    "rounding": { "mode": "HALF_UP", "scale": 0 }
+  }}]
+}'
+
+# Verify
+lexq analytics dry-run --version-id <vid> --debug --mock --json '{
+  "facts": { "user_tags": ["VIP", "verified"], "payment_amount": 100000, "lifetime_value": 500000 }
+}'
+```
+
+**Notes**
+
+- The `value` is always an array, even for a single tag: `"value": ["VIP"]`.
+- `ADD_TAG` writes to `user_tags` by default. Pass `targetVar` to append to a different `LIST_STRING` fact. The list is
+  created if absent, and re-adding an existing tag is a no-op.
+- An empty array makes `HAS_ALL` and `HAS_NONE` always true — they never look at the fact.
+- Rules fire in priority order, so a tag written by rule 0 is visible to rule 1.

package/skills/lexq-rules/SKILL.md

@@ -70,17 +70,53 @@ Conditions use a tree structure with two node types: `SINGLE` and `GROUP`.
 
 ### Operators
 
-| Operator                | 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 |
+Operators are constrained by the **left fact's type**. Using one outside its type is rejected
+by the server — check `lexq facts list` before choosing.
+
+| Fact type                     | Allowed operators                                                                                                  |
+|-------------------------------|--------------------------------------------------------------------------------------------------------------------|
+| `STRING`                      | `EQUALS`, `NOT_EQUALS`, `CONTAINS`, `IN`, `NOT_IN`                                                                 |
+| `NUMBER`                      | `EQUALS`, `NOT_EQUALS`, `GREATER_THAN`, `GREATER_THAN_OR_EQUAL`, `LESS_THAN`, `LESS_THAN_OR_EQUAL`, `IN`, `NOT_IN` |
+| `BOOLEAN`                     | `EQUALS`, `NOT_EQUALS`                                                                                             |
+| `LIST_STRING` / `LIST_NUMBER` | `HAS_ANY`, `HAS_ALL`, `HAS_NONE`                                                                                   |
+
+| Operator                                                                      | Description                                                | `value` |
+|-------------------------------------------------------------------------------|------------------------------------------------------------|---------|
+| `EQUALS` / `NOT_EQUALS`                                                       | Exact match / negation                                     | scalar  |
+| `GREATER_THAN` / `GREATER_THAN_OR_EQUAL` / `LESS_THAN` / `LESS_THAN_OR_EQUAL` | Numeric comparison                                         | scalar  |
+| `CONTAINS`                                                                    | **Substring** match on a STRING fact — not list membership | scalar  |
+| `IN` / `NOT_IN`                                                               | Scalar fact is (not) in the given list                     | array   |
+| `HAS_ANY`                                                                     | List fact has **at least one** of the given values         | array   |
+| `HAS_ALL`                                                                     | List fact has **all** of the given values                  | array   |
+| `HAS_NONE`                                                                    | List fact has **none** of the given values                 | array   |
+
+**`IN` vs `HAS_*` — mirrors of each other.** This is the most common mistake here:
+
+```json
+// scalar fact, list value
+{
+  "field": "region",
+  "operator": "IN",
+  "value": [
+    "KR",
+    "JP"
+  ],
+  "valueType": "LIST_STRING"
+}
+
+// list fact, list value
+{
+  "field": "user_tags",
+  "operator": "HAS_ANY",
+  "value": [
+    "VIP",
+    "GOLD"
+  ],
+  "valueType": "LIST_STRING"
+}
+```
+
+Do **not** use `CONTAINS` on a list fact — that idiom works in some rule engines but is rejected here.
 
 ### Value Types
 
@@ -145,10 +181,15 @@ Each rule can have multiple actions. Actions fire sequentially.
 | `INCREMENT_FACT`    | Increment a fact (cumulative add)                        | `targetVar`, `refVar`, `method`, `value` or `rate`, `rounding`                                      |
 | `EMIT_EVENT`        | Emit an event to an external integration (coupons, etc.) | `integrationId`, `eventPayload` (Map)                                                               |
 | `BLOCK`             | Block the transaction                                    | `reason`, `code`                                                                                    |
-| `EMIT_NOTIFICATION` | Send a notification                                      | `integrationId`, `target`, `notificationPayload` (Map)                                              |
+| `EMIT_NOTIFICATION` | Send a notification                                      | `integrationId`, `targetVar`, `notificationPayload` (Map)                                           |
 | `EMIT_WEBHOOK`      | Call an external URL                                     | `url`, `payloadTemplate`                                                                            |
 | `SET_FACT`          | Set a fact value (literal assignment)                    | `key`, `value`                                                                                      |
-| `ADD_TAG`           | Add a tag to the result                                  | `tag`                                                                                               |
+| `ADD_TAG`           | Append a tag to a list fact                              | `tag`, `targetVar` (optional, default `user_tags`)                                                  |
+
+**Two different `targetVar` meanings.** `EMIT_NOTIFICATION.targetVar` is a **read** — it names the
+fact holding the recipient (`phone_number`, `email`, `device_token`), and the action throws if that
+fact is absent from the request. `ADD_TAG.targetVar` is a **write** — the list is created if absent,
+and adding a tag that is already present is a no-op.
 
 ### Action Example: 10% Discount via MUTATE_FACT
 
@@ -305,4 +346,5 @@ Before creating rules, always:
 1. **Check available facts:** `lexq facts list`
 2. **Confirm the version is DRAFT:** `lexq versions get --group-id <gid> --id <vid>` → status must be `DRAFT`
 3. **Use exact fact keys** from the fact definitions (snake_case, case-sensitive)
-4. **Match value types** — a fact defined as `NUMBER` must receive numeric values, not strings
+4. **Match value types** — a fact defined as `NUMBER` must receive numeric values, not strings
+5. **Match the operator to the fact type** — list-typed facts accept only `HAS_ANY` / `HAS_ALL` / `HAS_NONE`

package/skills/lexq-simulation/SKILL.md

@@ -111,7 +111,7 @@ lexq analytics dry-run --version-id <vid> --debug --mock --json '{
         "ruleId": "...",
         "ruleName": "VIP 10% Discount",
         "matched": true,
-        "matchExpression": "(customer_tier == VIP AND payment_amount >= 100000)",
+        "matchExpression": "(customer_tier == 'VIP') && (payment_amount >= 100000)",
         "generatedActions": [
           {
             "type": "MUTATE_FACT",
@@ -143,26 +143,46 @@ lexq analytics dry-run --version-id <vid> --debug --mock --json '{
 
 ### Reading Decision Traces
 
-| Status          | Meaning                                     |
-|-----------------|---------------------------------------------|
-| `SELECTED`      | Rule matched and its actions fired          |
-| `NO_MATCH`      | Condition did not match the input           |
-| `NOT_SELECTED`  | Matched but excluded by conflict resolution |
-| `BLOCKED_MUTEX` | Blocked by mutex group constraint           |
-| `LOST_PRIORITY` | Lost to a higher-priority rule              |
-| `DROPPED_LIMIT` | Execution limit reached                     |
-| `ERROR`         | Rule evaluation failed                      |
+Each trace carries a `status` (what happened) and a `reasonCode` (why).
+
+| Status         | Meaning                                            |
+|----------------|----------------------------------------------------|
+| `SELECTED`     | Rule matched and its actions fired                 |
+| `NO_MATCH`     | Condition did not match, or could not be evaluated |
+| `NOT_SELECTED` | Matched but excluded by conflict resolution        |
+| `BLOCKED`      | Blocked by a mutex group or group activation limit |
+| `ERROR`        | Action execution failed                            |
 
 ### Reading Reason Codes
 
-| Code                  | Meaning                                                  |
-|-----------------------|----------------------------------------------------------|
-| `FINAL_WINNER`        | Successfully executed                                    |
-| `CONDITION_MISMATCH`  | Input facts didn't satisfy the condition                 |
-| `MUTEX_PRIORITY_LOST` | Another rule in the same mutex group had higher priority |
-| `MUTEX_LIMIT_REACHED` | Mutex group's max rules already fired                    |
-| `GROUP_LIMIT_REACHED` | Group's `executionLimit` reached                         |
-| `ACTION_ERROR`        | Action execution failed (e.g., webhook timeout)          |
+| Code                     | Meaning                                                  |
+|--------------------------|----------------------------------------------------------|
+| `FINAL_WINNER`           | Successfully executed                                    |
+| `CONDITION_MISMATCH`     | Condition not satisfied, or could not be evaluated       |
+| `EFFECTIVE_DATE_INVALID` | Outside the version's effective date range               |
+| `MUTEX_PRIORITY_LOST`    | Another rule in the same mutex group had higher priority |
+| `MUTEX_LIMIT_REACHED`    | Mutex group's max rules already fired                    |
+| `GROUP_PRIORITY_LOST`    | Another group in the same activation group won           |
+| `GROUP_LIMIT_REACHED`    | Group's `executionLimit` reached                         |
+| `ACTION_ERROR`           | Action execution failed (e.g., webhook timeout)          |
+| `ENGINE_ERROR`           | Internal engine failure                                  |
+
+#### `reasonDetail` on unevaluable conditions
+
+`CONDITION_MISMATCH` covers two different things, distinguished by `reasonDetail`:
+
+- **empty** — the condition was evaluated and did not match
+- **`Evaluation error: <code>`** — the condition could not be evaluated at all
+
+| Code                    | Meaning                                                            |
+|-------------------------|--------------------------------------------------------------------|
+| `FACT_NOT_PROVIDED`     | The rule references a fact absent from the request                 |
+| `FACT_TYPE_MISMATCH`    | The fact's runtime type does not match the condition               |
+| `UNSUPPORTED_FACT_TYPE` | Operator not valid for the fact's type (e.g. `CONTAINS` on a list) |
+| `MALFORMED_RULE`        | The stored rule is structurally invalid                            |
+
+A rule from another group referencing facts you did not send yields `FACT_NOT_PROVIDED` — this
+is normal, not an error.
 
 ## 3. Dry Run Compare