Validator Engine

The Validator Engine is the first line of defense in CertusOrdo's Autonomous Safety Layer. It inspects every AI agent transaction before commit, detecting anomalies and producing a confidence score that determines the transaction's fate.

Overview

Agent Output → [VALIDATOR ENGINE] → Confidence Score (0.0 - 1.0) → Decision Engine
                     │
                     ├── 12 Check Types
                     ├── Circuit Breaker
                     ├── Rate Limiting
                     └── PII/PHI Detection

Key Insight: Traditional systems validate inputs. CertusOrdo validates outputs — what the AI agent actually did, not what it was supposed to do.

---

Why This Matters

When an AI agent executes a transaction — transferring funds, accessing patient records, modifying documents — you need to know:

1. Is this within normal bounds? (Value, timing, scope)
2. Does this match expected behavior? (Behavioral analysis)
3. Is this compliant? (PII/PHI detection for HIPAA)
4. Should this proceed? (Confidence scoring)

The Validator Engine answers all four questions in under 10ms.

---

Validation Check Types

The engine runs 12 distinct validation checks against every transaction:

Check Type	What It Detects	Example
VALUE_BOUNDS	Transactions outside configured limits	Transfer > $10,000
SCHEMA	Invalid data structures	Missing required fields
TIMING	Unusual execution timing	3AM transaction for 9-5 agent
RATE_LIMIT	Excessive transaction velocity	100 requests/minute
SCOPE	Actions outside agent's permissions	HR agent accessing finance
SESSION	Session state violations	Expired or hijacked sessions
BEHAVIORAL	Deviation from learned patterns	Unusual action sequences
CONTENT_QUALITY	Low-quality outputs	Hallucinations, incomplete data
CONSISTENCY	State inconsistencies	Pre/post state mismatch
LATENCY	Abnormal processing times	30s response for 100ms task
PII_PHI	Sensitive data exposure	SSN, medical records in output
SECURITY	Potential attack patterns	Injection, privilege escalation

---

Confidence Scoring

Every validation produces a confidence score between 0.0 and 1.0:

1.0  ────────────────────────────────────────── PERFECT
      │
      │   ✅ All checks passed
      │   No anomalies detected
      │
0.95 ───────────────────────────────────────── EXCELLENT
      │
      │   Minor issues (low-severity)
      │   Auto-commit recommended
      │
0.80 ───────────────────────────────────────── GOOD
      │
      │   ⚠️ Some concerns detected
      │   Commit with monitoring
      │
0.70 ───────────────────────────────────────── CAUTION
      │
      │   Multiple issues or medium severity
      │   Human review recommended
      │
0.50 ───────────────────────────────────────── CONCERN
      │
      │   🔄 Significant problems
      │   Rollback and retry with corrections
      │
0.25 ───────────────────────────────────────── CRITICAL
      │
      │   🛑 Serious violations
      │   Rollback and terminate session
      │
0.0  ────────────────────────────────────────── THREAT
          🚨 Security threat detected
          Immediate termination

---

API Reference

Validate Transaction

POST /v1/safety/validate/validate
Content-Type: application/json
X-API-Key: your_api_key

Request Body:

{
  "transaction_id": "uuid",
  "agent_id": "uuid",
  "session_id": "uuid",
  "action_type": "api_call",
  "pre_state": {
    "balance": 10000.00
  },
  "post_state": {
    "balance": 5000.00,
    "transfer_to": "external_account"
  },
  "value_usd": 5000.00,
  "metadata": {
    "target_endpoint": "/api/transfer",
    "method": "POST"
  }
}

Response:

{
  "validation_id": "uuid",
  "transaction_id": "uuid",
  "passed": true,
  "confidence_score": 0.92,
  "anomaly_count": 1,
  "critical_count": 0,
  "error_count": 0,
  "anomalies": [
    {
      "type": "unusual_timing",
      "severity": "low",
      "code": "TIM001",
      "message": "Transaction outside normal hours",
      "details": {
        "expected_hours": "09:00-17:00",
        "actual_time": "18:30"
      }
    }
  ],
  "recommended_action": "COMMIT_WITH_WARNING",
  "processing_time_ms": 8.2
}

Get Anomaly History

GET /v1/safety/validate/anomalies?agent_id={uuid}&limit=100
X-API-Key: your_api_key

Returns historical anomalies for pattern analysis.

Get Validation Statistics

GET /v1/safety/validate/stats?org_id={uuid}&period=7d
X-API-Key: your_api_key

Returns aggregate statistics: pass rates, common anomalies, average confidence scores.

---

Configuration

Configure validation behavior per organization:

validation_config = {
    # Value bounds
    "max_transaction_value_usd": 10000.00,
    "max_daily_volume_usd": 100000.00,

    # Rate limiting
    "max_transactions_per_minute": 60,
    "max_transactions_per_hour": 500,

    # Timing windows
    "allowed_hours_start": "06:00",
    "allowed_hours_end": "22:00",
    "allowed_days": ["monday", "tuesday", "wednesday", "thursday", "friday"],

    # Behavioral thresholds
    "behavioral_deviation_threshold": 0.3,
    "latency_anomaly_multiplier": 3.0,

    # PII/PHI detection
    "pii_detection_enabled": True,
    "phi_detection_enabled": True,
    "pii_action": "flag",  # flag, mask, or block

    # Circuit breaker
    "circuit_breaker_threshold": 5,  # failures before open
    "circuit_breaker_timeout_seconds": 60
}

---

Circuit Breaker Pattern

The Validator Engine implements a circuit breaker to prevent cascade failures:

CLOSED → (failures exceed threshold) → OPEN → (timeout expires) → HALF-OPEN
   ↑                                                                    │
   └─────────────── (success) ──────────────────────────────────────────┘

States:

State	Behavior
CLOSED	Normal operation, all validations processed
OPEN	Validation bypassed, returns degraded confidence
HALF-OPEN	Testing recovery, limited validations processed

---

PII/PHI Detection

For HIPAA compliance, the Validator Engine scans transaction payloads for sensitive data:

Detected Patterns:

Category	Examples
PII	SSN, driver's license, passport numbers
PHI	Medical record numbers, diagnosis codes, prescription data
Financial	Credit card numbers, bank accounts, routing numbers
Authentication	API keys, passwords, tokens

Detection Actions:

• flag — Mark in anomaly report, allow transaction
• mask — Redact sensitive data, allow transaction
• block — Reject transaction, require remediation

---

Integration with Decision Engine

The Validator Engine doesn't make final decisions — it provides the intelligence the Decision Engine needs:

# Validator output feeds directly to Decision Engine
validation_result = await validator.validate_transaction(transaction)

decision = await decision_engine.evaluate(
    validation_id=validation_result.validation_id,
    transaction_id=validation_result.transaction_id,
    confidence_score=validation_result.confidence_score,
    anomaly_count=validation_result.anomaly_count,
    critical_count=validation_result.critical_count,
    anomalies=validation_result.anomalies
)

---

Performance Characteristics

Metric	Target	Typical
Latency (P50)	< 5ms	3ms
Latency (P99)	< 20ms	12ms
Throughput	10,000 TPS	15,000 TPS
Memory	< 100MB	45MB

---

Error Handling

The Validator Engine never blocks transactions due to internal errors:

try:
    result = await validator.validate(transaction)
except ValidationTimeoutError:
    # Return degraded result, don't block
    result = ValidationResult(
        passed=True,
        confidence_score=0.70,  # Conservative but allows progress
        recommended_action="COMMIT_WITH_WARNING",
        flags=["VALIDATION_DEGRADED"]
    )
except Exception as e:
    # Log and fail open with monitoring
    logger.error(f"Validation error: {e}")
    result = ValidationResult(
        passed=True,
        confidence_score=0.60,
        recommended_action="HOLD_FOR_REVIEW",
        flags=["VALIDATION_ERROR"]
    )

---

Next Steps

Once validated, transactions flow to the Decision Engine for autonomous commit/rollback decisions.