Extend session store with real-time event capture and health invariants

[AlexMikhalev]

Summary

Extend terraphim_sessions and terraphim-session-analyzer with real-time event-level capture, structured event types, and health invariant queries. Not a new crate -- the session store already has persistence, search, and KG enrichment.

Why Not a Separate Event Store?

Originally proposed as a new terraphim_event_store crate. But terraphim_sessions already:

• Parses session logs into structured records (costs, tool usage, patterns)
• Uses terraphim_persistence backends (SQLite, DashMap, S3)
• Supports KG-enriched search via Aho-Corasick automata
• Has rayon-based parallel processing

A session IS a sequence of events. Building parallel storage is over-engineering.

What's Missing (Gaps to Fill)

1. Real-time capture (not just post-hoc import)

Currently: session logs are imported after the session ends.
Needed: events captured as they happen during a session.

Add a SessionEventEmitter trait:

pub trait SessionEventEmitter: Send + Sync {
 async fn emit(&self, event: SessionEvent) -> Result<()>;
}

Hook into existing infrastructure:

• terraphim_hooks (PreToolUse, PostToolUse) -> emit events in real-time
• terraphim_service (search, LLM calls) -> emit events on each operation
• terraphim_multi_agent (agent decisions) -> emit events per decision

2. Structured event types

Currently: session-analyzer parses free-text logs.
Needed: typed event records for structured queries.

pub enum SessionEvent {
 LlmCall { model: String, tokens_in: u32, tokens_out: u32, cost_usd: f64, latency_ms: u64 },
 SearchExecuted { query: String, results_count: u32, relevance_scores: Vec<f64> },
 HookFired { hook_type: HookType, action: String, result: HookResult },
 Prediction { id: Ulid, source: String, predicted_outcome: String, confidence: f64 },
 Outcome { prediction_id: Ulid, actual_outcome: String, accuracy: f64 },
 ToolUse { tool: String, input_summary: String, success: bool, duration_ms: u64 },
}

These coexist with existing free-text session import -- typed events are a superset.

3. Health invariant queries

Currently: session-analyzer identifies patterns post-hoc.
Needed: automated drift/anomaly detection over rolling windows.

Invariants to detect:

• Model version drift: responses from unexpected model versions
• Score distribution shift: ranking scores deviate >2 sigma from rolling baseline
• Latency degradation: P95 response time exceeds historical threshold
• Error rate spike: error rate exceeds N% over rolling window
• Cost anomaly: per-session cost exceeds historical P95

Implementation: add check_invariants() method to session-analyzer that runs over the last N sessions/events and returns violations.

4. Correlation IDs

Currently: events within a session are sequential but not linked.
Needed: link related events (e.g., Prediction -> Outcome, PreToolUse -> PostToolUse for same invocation).

Add correlation_id: Option<Ulid> to SessionEvent. Events in the same logical operation share a correlation ID.

Affected Crates

• terraphim_sessions (primary -- add real-time emitter, event types)
• terraphim-session-analyzer (add health invariant queries)
• terraphim_hooks (emit events via SessionEventEmitter)
• terraphim_service (emit events for search/LLM calls)
• terraphim_types (add SessionEvent enum, HookType, etc.)
• terraphim_mcp_server (expose invariant check results as MCP resource)

Estimated Effort

~1 day for event types + real-time emitter + basic invariants. Ongoing integration per crate.

Part of

Epic #595

Downstream Dependents

• Budget-aware multi-model routing with per-task cost tracking #598 Budget-aware routing (cost tracking via session events)
• Enhanced learning capture: multi-hook pipeline with importance scoring #599 Enhanced learning capture (learning events are session events)
• EIDOS episodic reasoning: prediction-outcome tracking for agent evolution #601 EIDOS episodic reasoning (predictions/outcomes stored as session events)
• Confidence-driven knowledge graph promotion: EIDOS threshold gates KG entry creation #602 Confidence-driven KG promotion (queries session events for confidence scoring)