Emergent Learning Framework (ELF)

The Emergent Learning Framework (ELF) scripts have been updated to follow a robust error handling pattern. When interacting with or extending the framework via shell scripts, you should aim for the following standards to ensure system stability:

• Comprehensive Error Checking: Ensure 100% of commands are checked for success.
• Specific Exit Codes: Use specific exit codes in the range 0-99 instead of generic 1 to indicate the nature of the failure.
• Rich Error Messaging: Error messages should include Context, a suggested Fix, an error Code, and an error Category.
• Retry Logic: Implement retry mechanisms (e.g., 5 attempts with exponential backoff) for transient failures.
• Rollback Mechanisms: Ensure complete rollbacks with backups are performed if an operation fails midway.
• Validation: Use comprehensive validation for all inputs and states.
• Logging: Maintain complete logs for all operations.
• Security: Protect against common vulnerabilities like SQL injection in database operations.
• Graceful Degradation: Implement fallbacks so the system fails gracefully rather than hard-failing.

The Phase 2 Fraud Detection System is designed to enhance security by detecting adversarial agent logic, such as pump-and-dump attacks, selective validation, and coordinated manipulation. It uses an ensemble of 6 detection algorithms combined via Bayesian fusion to produce a fraud score.

Key Components:

• Detection Algorithms: 6 specialized detectors (e.g., success rate, temporal, coordinated manipulation).
• Scoring: Bayesian fusion of weak signals to achieve high accuracy.
• Response Actions: Automated actions including freeze (hard quarantine), reset, or escalate (CEO escalation).
• Baselines: Domain-specific statistical baselines to identify anomalies.

Dependencies: The system relies exclusively on the Python Standard Library (sqlite3, statistics, datetime, json, collections).

Database Requirements:

• Requires SQLite FTS5 for full-text search context matching.
• Windows/MSYS Fallback: If FTS5 is unavailable, the system should fallback to FTS4 or LIKE queries.

# Main fraud detection flow
def run_fraud_detection(heuristic_id: int) -> FraudReport:
    # Run all detectors
    signals = [
        detect_success_rate_anomaly(heuristic_id),
        detect_temporal_manipulation(heuristic_id),
        detect_coordinated_manipulation(heuristic_id),
        detect_unnatural_confidence_growth(heuristic_id),
        detect_application_selectivity(heuristic_id),
        detect_revival_gaming(heuristic_id)
    ]

    # Bayesian fusion
    fraud_score = bayesian_combine(signals, prior=0.05)

    # Classify
    classification = classify_fraud_score(fraud_score)

    # Store report
    report_id = store_fraud_report(heuristic_id, fraud_score, classification, signals)

    # Take action
    if classification == "fraud_confirmed":
        freeze_confidence(heuristic_id, report_id)
        escalate_to_ceo(heuristic_id, report_id)
    elif classification == "fraud_likely":
        tighten_rate_limits(heuristic_id, report_id)
        escalate_to_ceo(heuristic_id, report_id)
    elif classification == "suspicious":
        log_warning(heuristic_id, report_id)

    return FraudReport(...)

The Application Layer (apps/) contains user-facing applications such as UIs, CLIs, or APIs.

Key Principles:

• Acts as thin adapters over the Service Layer.
• Implements API versioning (e.g., /api/v1/).
• Handles input validation, transformation, error handling, and user feedback.

# apps/dashboard/backend/api/v1/heuristics.py
from fastapi import APIRouter, Depends, HTTPException
from elf.services import HeuristicsService, IHeuristicsService

router = APIRouter(prefix="/api/v1/heuristics", tags=["heuristics-v1"])

@router.post("/{id}/promote")
async def promote_heuristic(
    id: int,
    service: IHeuristicsService = Depends(get_heuristics_service)
):
    """
    Promote heuristic to golden rule.

    **Requires:** Confidence >= 0.8
    **Version:** 1.0 (stable)
    """
    try:
        heuristic = await service.promote_to_golden(id)
        return {"success": True, "heuristic": heuristic.dict()}
    except ValueError as e:
        raise HTTPException(400, detail=str(e))

The system uses Exponential Moving Average (EMA) to smooth confidence updates for heuristics, preventing single anomalous events from causing large swings in confidence.

When testing or implementing confidence updates, you can verify the smoothing effect using the following behaviors:

• Single Update Smoothing: A single UpdateType.SUCCESS or UpdateType.FAILURE should have a fractional impact rather than a discrete jump. For example, with an $\alpha=0.30$ (warmup), a single update should result in a much smaller delta than a discrete update.
• Noise Rejection: Random alternating updates (SUCCESS and FAILURE) should cause the confidence to stabilize near its baseline rather than oscillating wildly.
• Trend Detection: Sustained consecutive updates in one direction (e.g., 20 consecutive successes) should still allow the confidence to trend upward, albeit more slowly than a discrete system.
• Asymmetric Smoothing: The system is designed to be conservative. Increases in confidence should typically use a smaller $\alpha$ (smoother/slower) than decreases (faster/more reactive), following security best practices where trust is built slowly but lost quickly.

# Example of verifying a single update's smoothed impact
def test_single_update_smoothing():
    h_id = create_heuristic("test", "Test rule", confidence=0.5)

    # Apply one SUCCESS
    result = update_confidence(h_id, UpdateType.SUCCESS, force=True)

    # With EMA (α=0.30 warmup), the jump is damped
    assert result['new_confidence'] < 0.52
    assert result['new_confidence'] > 0.51
    assert result['smoothing_effect'] > 0.03