Language Reference

Overview

RuleDSL is a purpose-built language for writing business decision rules. For the published DET corpus, v1.0.2 produced byte-identical decisions on Windows x86_64 and Linux x86_64 when the engine/ABI, bytecode, canonical input, and evaluation options matched. This does not formally prove every possible rule and input.

A rule file contains one or more named rules. Each rule has a condition (when) and an action (then). Rules are evaluated in priority order. The first rule whose condition matches produces the decision.

Rule Structure

Every rule follows this pattern:

rule rule_name priority 100 {
  when <condition>;
  then <actions>;
}

Components

Evaluation Order

Rules are evaluated by priority (highest first). Among rules with equal priority, source order applies. The first match wins — no further rules are evaluated after a decision is reached.

Expressions & Operators

Comparison Operators

Logical Operators

Use parentheses to control evaluation order: (a or b) and c

Arithmetic Operators

Standard precedence: * and / bind tighter than + and -. Use parentheses when in doubt.

Operator Precedence (Highest to Lowest)

Decision Types

# Simple decisions
then allow;
then decline;
then review;

# Velocity limit (requires now_utc_ms in input)
then limit 200 USD per 1 D;

Data Types

Numeric Literals

Numbers support integer, decimal, and scientific notation:

when amount > 10000;        # integer
when rate > 0.05;           # decimal
when amount > 1e6;          # scientific notation (1,000,000)
when rate > 2.5e-3;         # decimal + exponent (0.0025)

Currency-Tagged Numbers

A 3-letter currency tag on a numeric literal is metadata in shipped v0.9. The engine compares the numeric value and does not automatically filter by currency, so add an explicit host-supplied currency condition:

when amount >= 10000 USD and currency == "USD";
when amount >= 8000 EUR and currency == "EUR";

Dotted Paths

Access nested fields with dot notation:

when customer.risk_level > 70 and merchant.category == "gambling";

Assignments & Computed Values

The then clause can set output fields alongside the decision. These appear in the result and can be used by downstream systems.

rule fraud_signal priority 100 {
  when amount > 3000 and ip_country in [NG, RU];
  then risk_score = 95,
       reason = "multi_signal_fraud",
       category = "high_risk",
       decline;
}

Assignments support arithmetic expressions:

then risk_score = (amount / 100) + velocity_1h, review;

Lists & Pattern Matching

IN Lists

Check if a value is a member of a list:

when ip_country in [TR, NG, RU, KP];
when channel in [ECOM, APP, WEB];

List items can be identifiers (bare words) or strings.

MATCH (Substring Matching)

Check if a text field contains a substring:

when email match "@example.com";
when card_bin match "41111";

Time & Velocity Limits

The limit decision expresses a velocity cap (an amount and a per window). The engine is stateless: the host computes counters, aggregates, and time-window fields, supplies any values the rule evaluates, and enforces the returned cap. now_utc_ms is validated as present but is not used computationally in v0.9:

then limit 500 USD per 1 D;    # max 500 USD per day
then limit 3 TRY per 1 H;      # max 3 transactions per hour

Time Units

Missing Values

If a referenced field is not provided in the input, it resolves to missing. This is not a normal "safe skip" contract:

• missing is a distinct value — not null, not zero, not empty string.
• A comparison involving missing can evaluate to false while emitting a runtime diagnostic; arithmetic can emit TYPE_MISMATCH and produce another missing value.
• UNKNOWN_PATH, TYPE_MISMATCH, and ASSIGN_VALUE_MISSING map to AX_ERR_RUNTIME=11. The decision struct can still be populated and evaluation can continue.
• The host must check code != AX_ERR_OK and handle the call fail-closed, regardless of a populated decision.

Validate required fields before evaluation; do not rely on missing-value behavior as control flow. See the v0.9 conformance status.

# Host must require customer.loyalty_tier before evaluating this rule
rule vip_bypass {
  when customer.loyalty_tier == "platinum";
  then allow;
}

Determinism Contract

The v0.9 language implementation controls implicit time, evaluation order, numeric mode, and locale inputs. For the published DET corpus, the shipped v1.0.2 Windows and Linux x86_64 binaries produced matching decisions under the same engine/ABI, bytecode, canonical input, and equivalent-option conditions. This is scenario evidence, not a formal proof over all rules and inputs:

Verified scope: same shipped v1.0.2 engine/ABI + same bytecode + canonical input + equivalent options produced byte-identical decisions on Windows x86_64 and Linux x86_64.

Complete Examples

Transaction Risk Scoring

rule block_sanctioned priority 200 {
  when ip_country in [KP, IR, SY];
  then reason = "sanctioned", decline;
}

rule high_risk_geo priority 100 {
  when amount > 5000 and ip_country in [NG, RU];
  then risk_score = 90, reason = "geo_high", decline;
}

rule review_medium priority 50 {
  when amount > 1000 and amount <= 5000;
  then risk_score = 60, reason = "medium_amount", review;
}

rule allow_default {
  when true;
  then risk_score = 10, reason = "baseline", allow;
}

Host-Supplied Spending Inputs and Limit Decisions

The host supplies transaction, device, aggregate, and time-window values; these rules evaluate those inputs but do not maintain a counter, window, or database.

rule block_new_device_high priority 100 {
  when is_new_device and amount > 2000;
  then reason = "new_device_risk", decline;
}

rule limit_daily priority 50 {
  when amount > 1000;
  then reason = "daily_cap", limit 500 USD per 1 D;
}

rule trusted_device priority 10 {
  when card_present and not is_new_device;
  then reason = "trusted", allow;
}

rule default_review {
  when true;
  then review;
}

Email & Channel Controls

rule flag_internal_email priority 100 {
  # Host supplies a normalized domain for exact matching
  when email_domain == "internal.corp";
  then reason = "internal_email", review;
}

rule block_risky_channel priority 50 {
  when channel in [ECOM, APP] and amount > 1000;
  then reason = "risky_channel", decline;
}

rule allow_other {
  when true;
  then allow;
}

Quick Reference

Keywords

Keywords are case-insensitive: WHEN, When, and when are equivalent.

Reserved Input Field

Further Reading

• Rule Cookbook — 12 copy-paste examples by business scenario
• Language Specification v1.0 — formal normative reference
• Error Reference — all 12 error codes with resolution steps
• Python Binding — quickstart for Python developers
• C# Binding — quickstart for .NET developers