Operating Modes

The Decision Engine supports three operating modes that control whether matched rules produce real actions or only recommendations. Modes allow teams to safely develop, test, and gradually roll out new automation rules.

Shadow Mode

Shadow mode evaluates all rules against live events but does not execute any actions. Results are logged for analysis, making it safe to test new rules against production traffic.

Behavior

• Rules are evaluated against every incoming event
• Matched rules and their would-be actions are recorded in the shadow log
• No actions are dispatched to any system (no gate commands, no drone dispatch, no alerts)
• Operators see no notifications from shadow rules
• Performance impact is minimal since only logging occurs

Configuration

decision_engine:
  mode: shadow
  shadow:
    log_destination: turqoa.shadow_decisions
    log_format: full          # full | summary
    retention_days: 30
    include_enrichment: true  # log the enrichment context for debugging
    comparison:
      enabled: true           # compare shadow decisions against live rules
      report_interval: hourly

Use Cases

• Testing new rules before promoting to advisory or live
• Validating rule changes after a configuration update
• Running A/B comparisons between rule sets
• Compliance auditing of potential automation decisions

Viewing Shadow Results

# View shadow decisions from the last hour
turqoa decisions list --mode shadow --since 1h

# Compare shadow vs. live decisions
turqoa decisions compare --shadow-ruleset v2.1 --live-ruleset v2.0 --since 24h

{
  "shadow_decision": {
    "decision_id": "sdec_20260406_001",
    "event_id": "evt_abc123",
    "mode": "shadow",
    "rules_matched": [
      {
        "rule": "AIS gap in restricted zone",
        "priority": 85,
        "would_execute": [
          { "action": "create_incident", "params": { "severity": "high" } },
          { "action": "dispatch_drone", "params": { "mission": "investigation" } }
        ]
      }
    ],
    "actual_actions_taken": [],
    "timestamp": "2026-04-06T14:22:00Z"
  }
}

Advisory Mode

Advisory mode evaluates rules and presents recommended actions to operators, who must manually approve or reject each recommendation before it executes. This is the recommended intermediate step between shadow and live.

Behavior

• Rules evaluate against all events
• When a rule matches, the recommended actions appear in the operator's advisory queue
• The operator reviews the recommendation with full context (event details, enrichment data, rule that triggered)
• The operator can approve all actions, approve selectively, modify actions, or dismiss
• Only approved actions are executed
• Dismissed recommendations are logged with the operator's reason

Configuration

decision_engine:
  mode: advisory
  advisory:
    queue_destination: command_center
    notification:
      sound: advisory_chime.wav
      priority: medium
    timeout:
      enabled: true
      duration_minutes: 5
      on_timeout: dismiss   # dismiss | escalate | auto_approve
    require_reason_on_dismiss: true
    operator_roles: [supervisor, senior_operator]

Operator Workflow

1. An event triggers a rule match
2. The advisory queue shows the recommendation:

ADVISORY: AIS gap in restricted zone
Priority: HIGH
Rule: maritime/ais_anomaly

Event: AIS gap for MV Nordic Star
  MMSI: 123456789
  Duration: 6 min
  Zone: LNG Terminal Restricted
  Risk Score: 62

Recommended Actions:
  ☐ Create incident (high)
  ☐ Dispatch drone (investigation)
  ☐ Escalate to operators

[Approve All] [Selected] [Dismiss]

3. The operator approves or dismisses
4. Approved actions execute immediately
5. The decision (including operator choice) is logged for audit

Advisory Timeout

If no operator acts within the configured timeout:

Live Mode

Live mode is fully autonomous. Rules evaluate and actions execute immediately without operator intervention. This is the production mode for established, well-tested rules.

Behavior

• Rules evaluate against all events
• Matched actions execute immediately and automatically
• Operators are notified of actions taken (post-hoc) based on severity
• All decisions are recorded in the audit log
• Emergency stop is always available

Configuration

decision_engine:
  mode: live
  live:
    max_actions_per_minute: 100
    circuit_breaker:
      enabled: true
      threshold: 50           # if > 50 actions in 1 minute, pause
      pause_duration_seconds: 30
      alert_on_trigger: true
    emergency_stop:
      enabled: true
      hotkey: "Ctrl+Shift+X"
      api_endpoint: /api/v1/decision-engine/stop
    post_action_notification:
      notify_on: [high, critical]
      channel: operator_console

Safety Controls

Live mode includes multiple safety mechanisms:

Emergency Stop

Immediately halt all Decision Engine automation:

# Via CLI
turqoa decision-engine stop --reason "Investigating false positives"

# Via API
curl -X POST https://api.turqoa.com/v1/decision-engine/stop \
  -H "Authorization: Bearer $TURQOA_API_KEY" \
  -d '{"reason": "Investigating false positives", "operator": "jsmith"}'

When emergency stop is triggered:

• All pending actions are cancelled
• The engine enters a paused state
• All operators receive a notification
• A supervisor must restart the engine

# Restart after emergency stop (requires supervisor role)
turqoa decision-engine start --confirmed-by "supervisor_jones"

Switching Between Modes

Per-Engine Mode

Set the global mode for the entire Decision Engine:

# Switch to advisory mode
turqoa decision-engine set-mode advisory --reason "Testing new maritime rules"

# Switch to live mode
turqoa decision-engine set-mode live --approved-by "supervisor_jones"

Per-Rule Mode

Individual rules can override the global mode:

RULE "New experimental gate rule"
  PRIORITY 60
  MODE shadow
  WHEN
    event.type = "gate_transaction"
    AND context.vehicle.first_visit = true
  THEN
    action: notify_operator(priority: "low")

This rule runs in shadow mode even if the engine is in live mode, which is useful for testing individual rules without affecting the rest of the system.

Mode Precedence

The effective mode is always the more restrictive of the engine mode and the rule mode. A rule cannot escalate beyond the engine's current mode.

Gradual Rollout Workflow

The recommended workflow for deploying new rules:

1. Write rule → 2. Deploy in Shadow → 3. Analyze shadow log
       ↓
4. Promote to Advisory → 5. Monitor operator approvals
       ↓
6. Promote to Live → 7. Monitor with circuit breaker

# Step 1-2: Deploy new rule in shadow
turqoa rules deploy --file ./rules/maritime/new_rule.yaml --mode shadow

# Step 3: Analyze after 48 hours
turqoa decisions analyze --rule "new_rule" --since 48h

# Step 4: Promote to advisory
turqoa rules promote --rule "new_rule" --mode advisory

# Step 5: Check operator approval rate after 1 week
turqoa decisions stats --rule "new_rule" --mode advisory --since 7d

# Step 6: Promote to live
turqoa rules promote --rule "new_rule" --mode live --approved-by "supervisor_jones"

Mode-Specific Logging

Each mode produces different log detail levels:

Shadow Mode Logs

{
  "log_type": "shadow_decision",
  "decision_id": "sdec_001",
  "event_id": "evt_abc",
  "rules_matched": ["rule_1", "rule_2"],
  "would_execute": [
    { "action": "notify_operator", "params": { "priority": "high" } },
    { "action": "dispatch_drone", "params": { "mission": "alarm_verification" } }
  ],
  "enrichment_snapshot": { "vessel_risk": 72, "zone": "restricted_a" },
  "actual_actions": []
}

Advisory Mode Logs

{
  "log_type": "advisory_decision",
  "decision_id": "adec_001",
  "event_id": "evt_abc",
  "rules_matched": ["rule_1"],
  "recommended_actions": [
    { "action": "dispatch_drone", "params": { "mission": "alarm_verification" } }
  ],
  "operator": "jsmith",
  "operator_decision": "approved",
  "operator_modifications": [],
  "time_to_decision_seconds": 12,
  "executed_actions": [
    { "action": "dispatch_drone", "params": { "mission": "alarm_verification" }, "status": "success" }
  ]
}

Live Mode Logs

{
  "log_type": "live_decision",
  "decision_id": "ldec_001",
  "event_id": "evt_abc",
  "pipeline_duration_ms": 11,
  "rules_matched": ["rule_1", "rule_3"],
  "conflict_resolution": "merge",
  "executed_actions": [
    { "action": "notify_operator", "status": "success", "latency_ms": 3 },
    { "action": "dispatch_drone", "status": "success", "latency_ms": 45 },
    { "action": "create_incident", "status": "success", "latency_ms": 8 }
  ],
  "total_execution_ms": 56
}

Log Retention

logging:
  retention:
    shadow: 30d
    advisory: 90d
    live: 365d
  export:
    format: json
    destination: s3://turqoa-audit/decision-logs/
    schedule: daily