Skip to content

Decision Engine

The Decision Engine is the autonomous brain of CertusOrdo's Safety Layer. It transforms validation results into actionable decisions — COMMIT, ROLLBACK, or ESCALATE — with 85%+ of decisions made without human intervention.

Overview

Validation Result → [DECISION ENGINE] → Action
                          │
                          ├── Policy Evaluation
                          ├── Confidence Thresholds
                          ├── Agent Reputation
                          └── Human Override Support

Key Insight: The goal isn't to prevent all mistakes — it's to handle them autonomously. Only decisions that genuinely require human judgment should interrupt your team.

The Decision Matrix

The Decision Engine uses a deterministic matrix to ensure consistent, explainable decisions:

Confidence Score Anomalies Retries Left Decision
ANY CRITICAL/SECURITY — ROLLBACK_AND_TERMINATE
≥ 95% None — COMMIT (autonomous)
≥ 80% Minor only — COMMIT_WITH_WARNING (auto)
≥ 70% Any — HOLD_FOR_REVIEW (human)
≥ 50% Correctable Yes ROLLBACK_AND_RETRY (auto)
≥ 50% Any No HOLD_FOR_REVIEW (human)
< 50% Correctable Yes ROLLBACK_AND_RETRY (auto)
< 50% Any No ROLLBACK_AND_TERMINATE

Decision Types

Autonomous Decisions (No Human Required)

Decision What Happens When Used
COMMIT Transaction finalized High confidence, no issues
COMMIT_WITH_WARNING Transaction finalized, flagged for review High confidence, minor issues
ROLLBACK_AND_RETRY Restore state, apply correction, retry Correctable issues detected
ROLLBACK_AND_TERMINATE Restore state, end session Critical/repeated failures

Human-Required Decisions

Decision What Happens When Used
HOLD_FOR_REVIEW Pause transaction, notify human Medium confidence, unclear path
ESCALATE Route to higher authority Policy requires approval

Autonomy Target: 85%+ of all decisions should be COMMIT, COMMIT_WITH_WARNING, or ROLLBACK_AND_RETRY.

API Reference

Evaluate Decision

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

Request Body:

{
  "validation_id": "6dc39482-fc77-4792-ad5e-f1d629e679c5",
  "transaction_id": "c3dbc393-494b-486d-9b38-eb75466a0011",
  "confidence_score": 0.72,
  "anomaly_count": 2,
  "critical_count": 0,
  "error_count": 1,
  "anomalies": [
    {
      "type": "value_bounds",
      "severity": "medium",
      "code": "VAL002",
      "message": "Transaction value exceeds soft limit",
      "correctable": true
    },
    {
      "type": "unusual_timing",
      "severity": "low",
      "code": "TIM001",
      "message": "Transaction outside normal hours"
    }
  ],
  "retry_count": 0,
  "max_retries": 3
}

Response:

{
  "decision_id": "uuid",
  "transaction_id": "uuid",
  "decision": "ROLLBACK_AND_RETRY",
  "status": "PENDING",
  "priority": "MEDIUM",
  "confidence_category": "CAUTION",
  "reasoning": {
    "primary_factor": "Correctable anomalies with retries remaining",
    "confidence_assessment": "72% confidence in CAUTION range",
    "anomaly_analysis": "1 correctable, 1 informational",
    "policy_applied": "default_auto_retry"
  },
  "correction_payload": {
    "strategy": "ADJUST_PARAMETER",
    "adjustments": [
      {
        "field": "value_usd",
        "action": "reduce",
        "target": 8000.00,
        "reason": "Bring within soft limit"
      }
    ]
  },
  "timeout_at": "2026-01-23T21:00:00Z",
  "requires_approval": false,
  "created_at": "2026-01-23T20:00:00Z"
}

Approve Decision (Human Override)

POST /v1/safety/decide/{decision_id}/approve
Content-Type: application/json
X-API-Key: your_api_key

Request Body:

{
  "approved_by": "user@company.com",
  "override_decision": "COMMIT",
  "reason": "Verified with customer, transaction is legitimate",
  "notes": "Customer confirmed wire transfer via phone"
}

Response:

{
  "decision_id": "uuid",
  "original_decision": "HOLD_FOR_REVIEW",
  "final_decision": "COMMIT",
  "status": "APPROVED",
  "approved_by": "user@company.com",
  "approved_at": "2026-01-23T20:15:00Z",
  "audit_trail": {
    "override_logged": true,
    "compliance_flagged": false
  }
}

Get Policies

GET /v1/safety/decide/policies?org_id={uuid}
X-API-Key: your_api_key

Returns organization-specific decision policies.

Get Decision Statistics

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

Returns decision distribution, autonomy rate, human intervention frequency.

Policy Engine

Organizations can customize decision behavior through policies:

decision_policy = {
    "name": "high_value_transactions",
    "description": "Stricter rules for transactions over $50K",

    # When this policy applies
    "conditions": {
        "value_usd_min": 50000.00,
        "action_types": ["wire_transfer", "bulk_payment"]
    },

    # Override default thresholds
    "thresholds": {
        "auto_commit_min_confidence": 0.95,  # Higher bar
        "auto_retry_min_confidence": 0.70,
        "human_review_timeout_minutes": 30   # Shorter timeout
    },

    # Required approvals
    "approvals": {
        "required_for": ["COMMIT"],
        "approvers": ["finance-team@company.com"],
        "min_approvers": 1
    },

    # Notification overrides
    "notifications": {
        "always_notify": ["cfo@company.com"],
        "channels": ["email", "sms"]
    }
}

Agent Reputation System

The Decision Engine tracks agent reliability over time:

agent_reputation = {
    "agent_id": "uuid",
    "reputation_score": 0.94,  # 0.0 - 1.0

    # Historical metrics
    "total_transactions": 15420,
    "successful_commits": 14890,
    "rollbacks": 530,
    "human_escalations": 45,

    # Recent performance (30 days)
    "recent_success_rate": 0.97,
    "recent_avg_confidence": 0.89,

    # Adjustments
    "threshold_adjustment": 0.05,  # Trusted agents get lower bar
    "auto_retry_bonus": 1         # Extra retry for high-rep agents
}

How Reputation Affects Decisions:

Reputation Effect
> 0.95 Confidence thresholds lowered by 5%
0.80-0.95 Standard thresholds
0.60-0.80 Confidence thresholds raised by 5%
< 0.60 All decisions require human review

Escalation Chains

For HOLD_FOR_REVIEW and ESCALATE decisions, the engine routes to the appropriate humans:

Level 1: Agent Owner (15 min timeout)
    │
    ↓ (no response)
Level 2: Team Lead (30 min timeout)
    │
    ↓ (no response)
Level 3: Department Head (60 min timeout)
    │
    ↓ (no response)
Level 4: Auto-rollback with incident report

Each level receives progressively more urgent notifications (email → SMS → voice call).

Timeout Handling

Decisions waiting for human approval have configurable timeouts:

Priority Default Timeout Timeout Action
CRITICAL 15 minutes Auto-rollback
HIGH 30 minutes Escalate to next level
MEDIUM 60 minutes Escalate to next level
LOW 4 hours Auto-rollback with warning

Audit Trail

Every decision is fully logged for compliance (SOC 2, SEC 17a-4):

{
  "decision_id": "uuid",
  "audit_entry": {
    "timestamp": "2026-01-23T20:00:00Z",
    "decision_type": "COMMIT_WITH_WARNING",
    "confidence_score": 0.82,
    "anomalies_detected": 1,
    "policy_applied": "default",
    "reasoning_chain": [
      "Confidence 82% >= 80% threshold",
      "No critical anomalies",
      "Agent reputation 0.94 (trusted)",
      "Decision: COMMIT_WITH_WARNING"
    ],
    "human_involvement": null,
    "execution_time_ms": 3.2,
    "hash": "sha256:abc123...",
    "previous_hash": "sha256:xyz789..."
  }
}

Integration Flow

# Complete flow from validation to decision
async def process_transaction(transaction):
    # Step 1: Validate
    validation = await validator_engine.validate(transaction)

    # Step 2: Decide
    decision = await decision_engine.evaluate(
        validation_id=validation.id,
        transaction_id=transaction.id,
        confidence_score=validation.confidence_score,
        anomaly_count=validation.anomaly_count,
        critical_count=validation.critical_count,
        anomalies=validation.anomalies
    )

    # Step 3: Execute decision
    match decision.decision:
        case "COMMIT":
            await transaction.commit()

        case "COMMIT_WITH_WARNING":
            await transaction.commit()
            await dashboard.flag(transaction)

        case "ROLLBACK_AND_RETRY":
            await transaction.rollback()
            correction = await correction_engine.generate(decision)
            await transaction.retry_with(correction)

        case "ROLLBACK_AND_TERMINATE":
            await transaction.rollback()
            await session.terminate()
            await notification_engine.alert(decision)

        case "HOLD_FOR_REVIEW":
            await transaction.hold()
            await notification_engine.request_approval(decision)

        case "ESCALATE":
            await escalation_chain.initiate(decision)

    return decision

Design Principles

  1. Deterministic — Same inputs always produce same outputs
  2. Explainable — Every decision includes full reasoning chain
  3. Fast — Target <10ms latency, never blocks on external calls
  4. Conservative — When uncertain, involve humans (fail-safe)
  5. Auditable — Every decision persisted with full context
  6. Configurable — Policies allow per-org customization
  7. Learning-Ready — Captures data for future ML improvements

Next Steps

When a decision requires correction, the Correction Engine generates the specific fixes to apply before retry.