Evaluation

The evaluation process determines whether a discount request is allowed based on policy rules.

Evaluation Flow

Order → PolicyEngine → Rules → Facts → Result

Input: An order with value, quantity, margin, and a proposed discount
Fact Calculation: Engine computes facts like calculated margin
Rule Evaluation: Each rule's conditions are checked against facts
Violation Collection: Failed conditions generate violations
Result: Approved/rejected with details

Basic Evaluation

import { PolicyEngine, defaultPolicy } from '@guardrail-sim/policy-engine';
import type { Order } from '@guardrail-sim/policy-engine';

const engine = new PolicyEngine(defaultPolicy);

const order: Order = {
  order_value: 5000,
  quantity: 100,
  product_margin: 0.4,
  customer_segment: 'gold',
};

const result = await engine.evaluate(order, 0.12);

Understanding Results

interface EvaluationResult {
  approved: boolean; // Whether discount is allowed
  violations: Violation[]; // Rules that were violated
  applied_rules: string[]; // All rules that triggered
  calculated_margin: number; // Final margin after discount
}

Approved Result

const result = await engine.evaluate(order, 0.12);
// {
//   approved: true,
//   violations: [],
//   applied_rules: ['margin_floor', 'max_discount', 'volume_tier'],
//   calculated_margin: 0.28
// }

Rejected Result

const result = await engine.evaluate(order, 0.3);
// {
//   approved: false,
//   violations: [
//     { rule: 'max_discount', message: 'Discount cannot exceed 25%' }
//   ],
//   applied_rules: ['max_discount'],
//   calculated_margin: 0.10
// }

How Rules Are Evaluated

Rules run in priority order (highest first). The engine:

Computes all facts from the order and proposed discount
Evaluates each rule's conditions against the facts
Collects violations from failed conditions
Returns approved=true only if no violations occurred

Computed Facts

The engine automatically calculates:

Fact	Formula
`calculated_margin`	`product_margin - proposed_discount`

Rule Priority

Higher priority numbers run first:

const rules = [
  { name: 'margin_floor', priority: 10 }, // Runs first (highest)
  { name: 'max_discount', priority: 5 }, // Runs second
  { name: 'volume_tier', priority: 1 }, // Runs third (lowest)
];

Multiple Violations

If multiple rules are violated, all violations are returned:

const result = await engine.evaluate({ order_value: 1000, quantity: 5, product_margin: 0.2 }, 0.25);
// {
//   approved: false,
//   violations: [
//     { rule: 'margin_floor', message: 'Margin below 15%' },
//     { rule: 'volume_tier', message: 'Quantity must be >= 100 for 15%+ discount' }
//   ],
//   ...
// }

UCP Error Codes

Violations include UCP-compatible error codes:

import { getUCPErrorCode } from '@guardrail-sim/policy-engine';

for (const violation of result.violations) {
  const ucpCode = getUCPErrorCode(violation.rule);
  // 'discount_code_invalid', 'discount_code_user_ineligible', etc.
}

Evaluation

On this page