Actions

When a policy rule's conditions are met, it triggers a violation event. The policy engine collects these violations and determines whether the discount request is approved.

Violation Events

Each rule defines an event that fires when conditions are met:

{
  name: 'margin_floor',
  conditions: {
    all: [{ fact: 'calculated_margin', operator: 'lessThan', value: 0.15 }]
  },
  event: {
    type: 'violation',
    params: {
      message: 'Calculated margin falls below 15% floor'
    }
  }
}

Evaluation Result

The evaluation result indicates whether the discount was approved:

interface EvaluationResult {
  /** Whether the discount was approved */
  approved: boolean;

  /** List of rule violations */
  violations: Violation[];

  /** Rules that were triggered */
  applied_rules: string[];

  /** Margin after applying discount */
  calculated_margin: number;
}

Approved (No Violations)

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

Rejected (Violations Found)

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
// }

UCP Error Codes

Violations map to UCP-compatible error codes for agentic commerce:

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

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

for (const violation of result.violations) {
  const ucpCode = getUCPErrorCode(violation.rule);
  console.log(`UCP Error: ${ucpCode}`);
}

Error Code Mapping

Violation Rule	UCP Error Code
`max_discount`	`discount_code_invalid`
`margin_floor`	`discount_code_invalid`
`volume_tier`	`discount_code_user_ineligible`
`stacking_not_allowed`	`discount_code_combination_disallowed`
`discount_expired`	`discount_code_expired`
`login_required`	`discount_code_user_not_logged_in`

Handling Violations

Check Before Applying

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

if (!result.approved) {
  // Show violations to user
  for (const v of result.violations) {
    console.log(`Cannot apply: ${v.message}`);
  }
  return;
}

// Safe to apply discount
applyDiscount(order, proposedDiscount);

Find Maximum Allowed

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

const maxDiscount = calculateMaxDiscount(order);
console.log(`Maximum allowed: ${maxDiscount * 100}%`);

MCP Tool Integration

The MCP server's evaluate_policy tool returns the same result structure:

{
  "approved": false,
  "violations": [
    {
      "rule": "margin_floor",
      "message": "Calculated margin (12%) falls below 15% floor"
    }
  ],
  "applied_rules": ["margin_floor"],
  "calculated_margin": 0.12
}

AI agents can use this response to:

Explain why a discount was rejected
Suggest an alternative discount level
Negotiate within policy limits

Actions

On this page