Stimulus-Response Routing

Stimulus arrives
│
├── Stage 1: Deterministic Routing (< 1ms)
│     └── Lookup source_name in WorkflowRegistry.routes
│           ├── MATCH → RoutingDecision { mode: Deterministic, confidence: 1.0 }
│           └── NO MATCH → fall through to Stage 2
│
└── Stage 2: LLM Classification (1-5s)
      └── RouterAgent receives stimulus content + headers
            ├── confidence ≥ threshold → RoutingDecision { mode: LlmClassified }
            └── confidence < threshold → StimulusRejected { reason: LowConfidence }

/// Aggregate Root — manages deterministic routes and optional LLM fallback.
struct WorkflowRegistry {
    routes: HashMap<String, WorkflowId>,    // source_name → workflow
    router_agent_id: Option<AgentId>,       // LLM fallback agent
    confidence_threshold: f64,              // default: 0.7
}

/// Immutable event envelope — created on ingestion, never mutated.
struct Stimulus {
    id: StimulusId,
    source: StimulusSource,
    content: Value,                         // raw JSON payload
    idempotency_key: Option<String>,
    headers: HashMap<String, String>,
    received_at: DateTime<Utc>,
}

/// Discriminated source type.
enum StimulusSource {
    Webhook { source_name: String },
    HttpApi,
    Stdin,
    TemporalSignal,
}

/// Output of the routing pipeline.
struct RoutingDecision {
    workflow_id: WorkflowId,
    confidence: f64,                        // 1.0 for deterministic, 0.0–1.0 for LLM
    mode: RoutingMode,
}

enum RoutingMode {
    Deterministic,
    LlmClassified,
}

/// Why a stimulus was not routed.
enum RejectionReason {
    LowConfidence,
    NoRouterConfigured,
    HmacInvalid,
    IdempotentDuplicate,
}

POST /v1/webhooks/github
Headers:
  X-Aegis-Signature: sha256=a1b2c3...
  Content-Type: application/json
Body: {"action": "push", ...}
│
├── 1. Extract source_name from URL path ("github")
├── 2. Resolve secret: AEGIS_WEBHOOK_SECRET_GITHUB env var
├── 3. Compute HMAC-SHA256(secret, raw_body)
├── 4. Constant-time compare via `subtle` crate
│     ├── MATCH → proceed to routing pipeline
│     └── MISMATCH → 401 Unauthorized, publish StimulusRejected { reason: HmacInvalid }

SensorService
│
├── StdinSensor
│     └── Reads newline-delimited JSON from stdin
│     └── Each line is parsed as a Stimulus and routed through the pipeline
│
├── (Custom sensors implement the Sensor trait)
│
└── Lifecycle
      ├── Started during orchestrator boot
      ├── Each sensor runs in a dedicated tokio::spawn task
      └── Graceful shutdown via CancellationToken propagation

#[async_trait]
trait Sensor: Send + Sync {
    /// Human-readable name for logging and metrics.
    fn name(&self) -> &str;

    /// Run the sensor loop. Implementations should select! on the
    /// cancellation token to support graceful shutdown.
    async fn run(
        &self,
        tx: mpsc::Sender<Stimulus>,
        cancel: CancellationToken,
    ) -> Result<()>;
}