/**
 * intent_router.h
 * موجه النوايا - نظام التوجيه الديناميكي
 * Intent Router - Dynamic Routing System
 *
 * Routes incoming intents from ring buffer to appropriate KAR agents
 * based on intent type, priority, and system state.
 *
 * Author: Ahmad Ali Parr
 * License: Sovereign Source
 */

#ifndef ASOS_INTENT_ROUTER_H
#define ASOS_INTENT_ROUTER_H

#include "intent_schema.h"

/* Forward declarations */
struct IntentRing;
struct KARWorkerPool;

/* ═══════════════════════════════════════════════════════════════
 * Router Configuration | تكوين الموجه
 * ═══════════════════════════════════════════════════════════════ */

/**
 * RouterConfig - Configuration for intent routing
 */
struct RouterConfig {
    unsigned int num_workers;        /* Number of worker threads */
    unsigned int max_queue_depth;    /* Max pending intents */
    unsigned int routing_timeout_ms; /* Timeout for routing decision */
    bool enable_load_balancing;      /* Distribute across workers */
    bool enable_priority_preempt;    /* Allow high-priority preemption */
};

/* Default router configuration */
#define DEFAULT_ROUTER_CONFIG {     \
    .num_workers = 4,               \
    .max_queue_depth = 256,         \
    .routing_timeout_ms = 1000,     \
    .enable_load_balancing = true,  \
    .enable_priority_preempt = true \
}

/* ═══════════════════════════════════════════════════════════════
 * Routing Decision | قرار التوجيه
 * ═══════════════════════════════════════════════════════════════ */

/**
 * RoutingDecision - Where and how to process an intent
 */
struct RoutingDecision {
    unsigned int worker_id;          /* Which worker thread */
    unsigned int agent_id;           /* Which KAR agent */
    bool use_accelerator;            /* Route to NPU/FPGA */
    unsigned int estimated_cost_ns;  /* Estimated processing time */
};

/* ═══════════════════════════════════════════════════════════════
 * Router Lifecycle | دورة حياة الموجه
 * ═══════════════════════════════════════════════════════════════ */

/**
 * router_init - Initialize the intent router
 * @ring: Ring buffer to monitor
 * @config: Router configuration
 *
 * Returns: 0 on success, negative error code on failure
 */
int router_init(struct IntentRing *ring, const struct RouterConfig *config);

/**
 * router_shutdown - Shutdown the router and worker pool
 */
void router_shutdown(void);

/* ═══════════════════════════════════════════════════════════════
 * Routing Operations | عمليات التوجيه
 * ═══════════════════════════════════════════════════════════════ */

/**
 * router_route_intent - Route a single intent to KAR
 * @intent: Intent to route
 * @decision_out: Output for routing decision
 *
 * Returns: 0 on success, negative error code on failure
 *
 * This is called by the ring buffer consumer to determine where
 * to send the intent for processing.
 */
int router_route_intent(const struct SystemIntent *intent,
                        struct RoutingDecision *decision_out);

/**
 * router_enqueue_intent - Enqueue intent to worker thread
 * @intent: Intent to enqueue
 * @decision: Routing decision from router_route_intent()
 *
 * Returns: 0 on success, negative error code on failure
 */
int router_enqueue_intent(const struct SystemIntent *intent,
                          const struct RoutingDecision *decision);

/* ═══════════════════════════════════════════════════════════════
 * Router Statistics | إحصائيات الموجه
 * ═══════════════════════════════════════════════════════════════ */

/**
 * RouterStats - Runtime statistics for monitoring
 */
struct RouterStats {
    uint64_t total_routed;           /* Total intents routed */
    uint64_t routing_errors;         /* Failed routing attempts */
    uint64_t queue_full_rejects;     /* Rejected due to queue full */
    uint64_t avg_routing_time_ns;    /* Average routing decision time */
    unsigned int current_queue_depth;/* Current pending intents */
};

/**
 * router_get_stats - Get current router statistics
 * @stats_out: Output buffer for statistics
 *
 * Returns: 0 on success
 */
int router_get_stats(struct RouterStats *stats_out);

#endif /* ASOS_INTENT_ROUTER_H */