7.2 The Rule Resolution Algorithm

The Rule Resolution Algorithm

At runtime, a Pega application never executes a hardcoded script or static class file. Instead, whenever a case lifecycle invokes an action—whether loading a Section, evaluating a Data Transform, triggering a Flow Action, or calculating a Declare Expression—the platform initiates the Rule Resolution Algorithm.

The Rule Resolution Algorithm is the core search engine of the Pega Platform. It is a deterministic, multi-phase decision process that searches the PegaRULES database and in-memory caches to identify and execute the single most appropriate rule instance for an authenticated user at that exact microsecond. Understanding how Pega selects winning rules, manages rule availability, and handles class inheritance is essential for designing resilient enterprise architectures.

---

1. Purpose and Scope of Rule Resolution

Rule Resolution implements the object-oriented principle of dynamic polymorphism within Pega's Enterprise Class Structure (ECS). It allows general business logic defined at an enterprise or framework layer to be dynamically specialized, overridden, or extended by line-of-business implementation layers without modifying the underlying base application.

Which Objects Use Rule Resolution?

• Applicable Objects: Most rules—specifically those inheriting from abstract base class Rule- that have the Use Rule Resolution? flag enabled (such as Rule-Obj-Flow, Rule-HTML-Section, Rule-Obj-Model, and Rule-Obj-Property).
• Non-Applicable Objects: System data instances (Data-), Operator records, Access Groups, Database tables, Class records (Rule-Obj-Class), and Ruleset definitions do NOT use rule resolution. These records are queried directly by exact primary key lookup rather than algorithmic inheritance searching.

---

2. The Rules Assembly Cache (Rule Resolution Cache)

Executing a database query across millions of rule records every time an operator clicks a button would cause unacceptable latency. To deliver sub-millisecond execution speeds, Pega utilizes an intelligent, two-tiered in-memory cache known as the Rule Resolution Cache (or Rules Assembly Cache):

+-------------------------------------------------------------------------+
|                   RULES ASSEMBLY CACHE ARCHITECTURE                     |
+-------------------------------------------------------------------------+
| 1. Rule Invocation Request                                              |
|    └─ Context: Applies-To Class + Rule Name + Ruleset Stack             |
|                                                                         |
| 2. Cache Check (In-Memory Hash Lookup)                                  |
|    ├─ HIT: Directly invoke pre-compiled Java bytecode (< 1 ms)          |
|    └─ MISS: Execute Full 6-Step Rule Resolution Algorithm               |
|                                                                         |
| 3. Algorithm Resolves Winning Rule Record                               |
|    ├─ Extract XML/BLOB from Database                                    |
|    ├─ Compile Rule into executable Java Bytecode                        |
|    ├─ Place compiled Bytecode into Rules Assembly Cache                 |
|    └─ Execute Rule                                                      |
+-------------------------------------------------------------------------+

• Cache Hit: When a rule is invoked, the engine checks the Rules Assembly Cache for an entry matching the user's active ruleset stack, class context, and circumstance values. If found, the pre-compiled Java bytecode executes instantaneously without database access.
• Cache Miss: If the rule is invoked for the first time following a server restart or cache invalidation, the engine executes the full 6-Step Rule Resolution Algorithm against the PegaRULES database, compiles the winning rule into Java bytecode, stores it in the cache, and executes it.
• Cache Invalidation: The cache is automatically synchronized across cluster nodes using system pulse mechanisms (pr_sys_statusnodes). When an architect checks in, updates, or deletes a rule, cache entries affected by that rule are marked dirty and re-compiled on demand.

---

3. The 6-Step Rule Resolution Search Pipeline

When a cache miss occurs, the Pega engine executes a structured, six-step candidate filtering and ranking pipeline:

+-------------------------------------------------------------------------+
|               THE 6-STEP RULE RESOLUTION SEARCH PIPELINE                |
+-------------------------------------------------------------------------+
| STEP 1: Filter Database by Rule Type and Class Inheritance              |
|         - Query PegaRULES database for matching Rule Name and Type      |
|         - Inspect Applies-To class, Pattern & Directed ancestor classes |
+-------------------------------------------------------------------------+
                                     |
                                     v
| STEP 2: Discard Inactive Rulesets                                       |
|         - Eliminate any candidate rule whose ruleset is NOT in the      |
|           requestor's assembled runtime Ruleset Stack                   |
+-------------------------------------------------------------------------+
                                     |
                                     v
| STEP 3: Filter by Rule Availability                                     |
|         - Discard rules marked 'Not Available'                          |
|         - Retain 'Blocked' rules to halt resolution if selected         |
+-------------------------------------------------------------------------+
                                     |
                                     v
| STEP 4: Discard Disallowed Ruleset Versions                             |
|         - Discard candidates with version numbers higher than the       |
|           maximum version allowed by the application stack / ruleset    |
+-------------------------------------------------------------------------+
                                     |
                                     v
| STEP 5: Rank Remaining Candidates                                       |
|         - 1. Class: Exact class match > Pattern/Directed parent classes |
|         - 2. Ruleset Version: Highest allowed version number first      |
|         - 3. Circumstance: Qualified circumstance > Base (unqualified)  |
|         - 4. Availability: Available, Final, Blocked, Withdrawn         |
+-------------------------------------------------------------------------+
                                     |
                                     v
| STEP 6: Determine Winning Rule & Verify Availability                    |
|         - Select the single highest-ranking candidate                   |
|         - If Available / Final: Execute the rule                        |
|         - If Blocked: HALT execution immediately and throw error        |
|         - If Withdrawn: Discard ruleset version candidates and retry    |
+-------------------------------------------------------------------------+

Step 1: Filter Candidates by Rule Type and Class Inheritance

The engine queries the database for all rules matching the requested rule identifier (e.g., Data Transform SetCustomerDefaults) and Rule Type (Rule-Obj-Model). It searches the exact Applies-To class of the current context, followed by all ancestor classes up the class hierarchy using both Pattern Inheritance (name prefix delimited by hyphens) and Directed Inheritance (explicit parent class specified on the class rule form).

Step 2: Discard Candidates Outside the Active Ruleset Stack

The engine cross-references the candidate list against the requestor's active runtime ruleset stack (assembled from their Operator ID, Access Group, and Application records). Any candidate belonging to a ruleset that is NOT present in the user's stack is immediately discarded.

Step 3: Filter by Rule Availability

The engine checks the Availability status of each remaining candidate:

• Rules marked as Not Available (No) are discarded immediately. The engine acts as if these rule records do not exist.
• Rules marked as Blocked are retained in the candidate list. This is critical: if a Blocked rule is determined to be the winning candidate later in the pipeline, it must halt resolution rather than allow a parent class rule to execute.

Step 4: Discard Disallowed Ruleset Versions

The engine examines the version numbers of remaining candidates against the maximum allowed version specified in the ruleset stack. If the stack restricts MyCo:01-02, any candidates residing in MyCo:01-03-01 are discarded.

Step 5: Rank Remaining Candidates

The surviving candidates are sorted according to a rigid, deterministic ranking hierarchy:

1. Class Hierarchy (Specificity): Candidates matching the exact Applies-To class of the calling context rank highest. Candidates in parent classes rank lower in order of inheritance traversal (immediate parent > grandparent > enterprise > Work- > @baseclass).
2. Ruleset Version: Within the same class, candidates in higher ruleset versions rank above candidates in lower versions (e.g., 01-02-05 beats 01-01-10).
3. Circumstancing: A circumstanced rule variant that matches the current runtime property, date, or multivariate condition ranks higher than an uncircumstanced (base) rule.
4. Availability State: Rank according to Available, Final, Withdrawn, and Blocked precedence.

Step 6: Determine Winning Rule and Verify Availability

The engine inspects the single highest-ranking candidate:

• If Available (Yes) or Final: The rule is selected as the winner, compiled into bytecode, cached, and executed.
• If Blocked: The engine halts execution immediately and generates a fatal runtime exception. It does NOT fall back to a parent class.
• If Withdrawn: The candidate and all lower versions in that specific ruleset at that class level are eliminated, and resolution continues searching parent classes or lower rulesets.

4. Rule Availability States & Runtime Behavior

Rule availability governs whether a rule can be executed, copied, or evaluated by the Rule Resolution Algorithm. Pega provides five distinct availability states configured on the rule form:

+-------------------------------------------------------------------------+
|                        RULE AVAILABILITY STATES                         |
+-------------------------------------------------------------------------+
| 1. AVAILABLE (Yes)      - Normal execution; open for inheritance        |
| 2. NOT AVAILABLE (No)   - Invisible to resolution; behaves as if missing|
| 3. BLOCKED              - Halts execution; throws error; blocks parents |
| 4. FINAL                - Executable; CANNOT be overridden downstream   |
| 5. WITHDRAWN            - Drops ruleset versions; search PARENT classes |
+-------------------------------------------------------------------------+

1. Available (Yes)

• The standard operational state for all active rules.
• The rule is visible to rule resolution, can be executed at runtime, and can be specialized or overridden in child classes or higher ruleset versions.

2. Not Available (No)

• The rule is treated as if it does not exist in that specific ruleset version.
• It is discarded in Step 3 of the Rule Resolution Algorithm.
• Inheritance Impact: If a lower ruleset version or a parent class contains an Available version of the rule, Pega will find and execute that version instead. Commonly used by developers to temporarily disable a newly created rule version without deleting the rule record.

3. Blocked

• The rule is found by rule resolution, but its explicit purpose is to halt execution and prevent processing.
• If a Blocked rule is selected as the top candidate in Step 6, Pega throws a fatal runtime exception.
• Crucial Architectural Impact: A Blocked rule acts as a solid barrier. It strictly prevents rule resolution from traversing up the class inheritance hierarchy. Pega will NOT execute a rule from a parent class if a child class contains a winning Blocked rule.

4. Final

• The rule is fully available for runtime execution and can be circumstanced.
• Guardrail Protection: A Final rule CANNOT be overridden or extended in child classes or in higher ruleset versions by downstream applications.
• Only rules residing in the exact same ruleset can be modified if unlocked.
• Standard Pega platform engine rules (such as core security authentication flows or low-level database persist routines) are marked as Final to guarantee platform stability and prevent enterprise tampering.

5. Withdrawn

• The rule is marked as withdrawn to signify that it should no longer be used.
• Scope of Withdrawal: Marking a rule as Withdrawn removes the rule itself AND all lower versions of that rule within the same ruleset at that specific class level from consideration.
• Crucial Architectural Impact: Unlike a Blocked rule, a Withdrawn rule does NOT halt processing. Instead, it allows rule resolution to continue searching up the class inheritance tree (Pattern and Directed parent classes) or in lower rulesets in the stack to find an active implementation.

5. Crucial Exam Comparison: Blocked vs. Withdrawn

The architectural distinction between Blocked and Withdrawn availability states is one of the most frequently tested topics on the Pega Certified System Architect exam. Architects must understand their opposing behaviors during class inheritance traversal:

Architectural Scenario Walkthrough

Consider an enterprise application hierarchy with the following structure:

• Parent Framework Class: MyCo-Work
  • Rule: CalculateTax (Version MyCoFW:01-01-01, Available)
• Child Implementation Class: MyCo-Auto-Work
  • Rule: CalculateTax (Version MyCoAuto:01-01-01, Available)
  • Rule: CalculateTax (Version MyCoAuto:01-01-05, New Version)

Scenario A: Version 01-01-05 is set to WITHDRAWN

• When CalculateTax executes in class MyCo-Auto-Work:
• Version 01-01-05 is Withdrawn. This automatically eliminates 01-01-05 and its lower version 01-01-01 in ruleset MyCoAuto at class MyCo-Auto-Work.
• Rule resolution does not halt. It traverses up the class inheritance tree to MyCo-Work.
• Result: Pega successfully resolves and executes CalculateTax in MyCo-Work (MyCoFW:01-01-01).

Scenario B: Version 01-01-05 is set to BLOCKED

• When CalculateTax executes in class MyCo-Auto-Work:
• Version 01-01-05 is ranked as the winning candidate for class MyCo-Auto-Work.
• In Step 6, the engine detects that the winning candidate is Blocked.
• Result: Pega halts execution immediately and throws a runtime exception. It refuses to search MyCo-Work. Processing aborts.