feat: implement F-score tracking and analytics (issue #91) (#140)

## Summary

Implements comprehensive F-score tracking and analytics system as
requested in issue #91. This PR introduces dedicated F-score calculation
and tracking infrastructure for precision/recall metrics targeting
manager/executive use cases in MVP Phase 4.

### Key Features

- **Type-Safe F-score Domain Types**: Created validated newtypes using
`nutype` for `FScore`, `Precision`, `Recall`, `Beta`, and
`ConfidenceLevel` with proper validation ranges
- **F-score Calculation Engine**: Implements harmonic mean calculation
with support for configurable beta values (F1, F2, F-beta scores)
- **EventCore Integration**: Multi-stream event sourcing with
`RecordModelFScore` and `RecordApplicationFScore` commands
- **Time-Series Tracking**: `FScoreDataPoint` infrastructure for
tracking F-score trends over time with confidence intervals
- **Demo Data Generation**: Comprehensive demo data generator for MVP
visualization with realistic time-series data
- **Comprehensive Test Coverage**: 14 new passing tests covering domain
logic, EventCore integration, and edge cases

### Technical Implementation

- **Domain Types**: All F-score types include validation ensuring values
are finite and within valid ranges (0.0-1.0)
- **Event Sourcing**: Commands emit `FScoreCalculated` and
`ApplicationFScoreCalculated` events to appropriate streams
- **State Management**: `MetricsState` tracks F-score history for both
model versions and applications
- **Demo Data**: Includes provider comparison data, application-specific
trends, and performance categorization

### Recent Refactoring (per PR review)

Based on comprehensive type-driven development review:

1. **Eliminated Primitive Obsession**:
   - Extracted stream ID prefix constants to remove string literals
- Created `PerformanceCategory` domain type replacing raw strings in
demo data
   - Replaced magic numbers in tests with test_data constants

2. **Reduced Code Duplication**:
- Introduced `FScoreCommand` trait to share common logic between
`RecordModelFScore` and `RecordApplicationFScore`
   - Consolidated F-score calculation logic

3. **Improved Type Safety**:
- Fixed string `contains()` usage on `ApplicationId` with proper
equality checks
   - Enhanced readability and maintainability throughout metrics module

### Testing

All 289 tests pass including:
- F-score calculation accuracy with harmonic mean formula
- EventCore command execution and event emission
- Domain type validation and edge cases
- Demo data generation with realistic patterns

Closes #91

🤖 Generated with [Claude Code](https://claude.ai/code)

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: jwilger

dhat-heap.json

@@ -1,5 +1,7 @@
 //! EventCore commands for the Union Square domain
 
+pub mod metrics_commands;
 pub mod version_commands;
 
+pub use metrics_commands::{RecordApplicationFScore, RecordModelFScore};
 pub use version_commands::{DeactivateVersion, RecordVersionChange, RecordVersionUsage};

src/domain/commands/metrics_commands.rs

@@ -15,6 +15,7 @@ use std::collections::HashMap;
 use crate::domain::{
     events::DomainEvent,
     llm::ModelVersion,
+    metrics::Timestamp,
     session::SessionId,
     types::ChangeReason,
     version::{TrackedVersion, VersionChangeId},
@@ -106,7 +107,7 @@ impl CommandLogic for RecordVersionUsage {
                 DomainEvent::VersionFirstSeen {
                     model_version: self.model_version.clone(),
                     session_id: self.session_id.clone(),
-                    first_seen_at: chrono::Utc::now(),
+                    first_seen_at: Timestamp::now(),
                 }
             );
         }
@@ -119,7 +120,7 @@ impl CommandLogic for RecordVersionUsage {
             DomainEvent::VersionUsageRecorded {
                 model_version: self.model_version.clone(),
                 session_id: self.session_id.clone(),
-                recorded_at: chrono::Utc::now(),
+                recorded_at: Timestamp::now(),
             }
         );
 
@@ -191,7 +192,7 @@ impl CommandLogic for RecordVersionChange {
             to_version: self.to_version.clone(),
             change_type,
             reason: self.reason.clone(),
-            changed_at: chrono::Utc::now(),
+            changed_at: Timestamp::now(),
         };
 
         // Write to both streams
@@ -265,7 +266,7 @@ impl CommandLogic for DeactivateVersion {
             DomainEvent::VersionDeactivated {
                 model_version: self.model_version.clone(),
                 reason: self.reason.clone(),
-                deactivated_at: chrono::Utc::now(),
+                deactivated_at: Timestamp::now(),
             }
         );
 

src/domain/commands/mod.rs

@@ -3,11 +3,11 @@
 //! This module defines all domain events that are stored
 //! in the event store using EventCore.
 
-use chrono::{DateTime, Utc};
 use serde::{Deserialize, Serialize};
 
 use crate::domain::{
     llm::{ModelVersion, RequestId, ResponseMetadata},
+    metrics::{SampleCount, Timestamp},
     session::{ApplicationId, SessionId, SessionStatus},
     types::{ChangeReason, ErrorMessage, LlmParameters, Prompt, ResponseText, Tag},
     user::{DisplayName, EmailAddress, UserId},
@@ -23,17 +23,17 @@ pub enum DomainEvent {
         session_id: SessionId,
         user_id: UserId,
         application_id: ApplicationId,
-        started_at: DateTime<Utc>,
+        started_at: Timestamp,
     },
     SessionEnded {
         session_id: SessionId,
-        ended_at: DateTime<Utc>,
+        ended_at: Timestamp,
         final_status: SessionStatus,
     },
     SessionTagged {
         session_id: SessionId,
         tag: Tag,
-        tagged_at: DateTime<Utc>,
+        tagged_at: Timestamp,
     },
 
     // LLM Request Events
@@ -43,33 +43,33 @@ pub enum DomainEvent {
         model_version: ModelVersion,
         prompt: Prompt,
         parameters: LlmParameters,
-        received_at: DateTime<Utc>,
+        received_at: Timestamp,
     },
     LlmRequestStarted {
         request_id: RequestId,
-        started_at: DateTime<Utc>,
+        started_at: Timestamp,
     },
     LlmResponseReceived {
         request_id: RequestId,
         response_text: ResponseText,
         metadata: ResponseMetadata,
-        received_at: DateTime<Utc>,
+        received_at: Timestamp,
     },
     LlmRequestFailed {
         request_id: RequestId,
         error_message: ErrorMessage,
-        failed_at: DateTime<Utc>,
+        failed_at: Timestamp,
     },
     LlmRequestCancelled {
         request_id: RequestId,
-        cancelled_at: DateTime<Utc>,
+        cancelled_at: Timestamp,
     },
 
     // Version Tracking Events
     VersionFirstSeen {
         model_version: ModelVersion,
         session_id: SessionId,
-        first_seen_at: DateTime<Utc>,
+        first_seen_at: Timestamp,
     },
     VersionChanged {
         change_id: VersionChangeId,
@@ -78,40 +78,61 @@ pub enum DomainEvent {
         to_version: ModelVersion,
         change_type: VersionComparison,
         reason: Option<ChangeReason>,
-        changed_at: DateTime<Utc>,
+        changed_at: Timestamp,
     },
     VersionUsageRecorded {
         model_version: ModelVersion,
         session_id: SessionId,
-        recorded_at: DateTime<Utc>,
+        recorded_at: Timestamp,
     },
     VersionDeactivated {
         model_version: ModelVersion,
         reason: Option<ChangeReason>,
-        deactivated_at: DateTime<Utc>,
+        deactivated_at: Timestamp,
+    },
+
+    // F-score and Metrics Events
+    FScoreCalculated {
+        session_id: SessionId,
+        model_version: ModelVersion,
+        f_score: crate::domain::metrics::FScore,
+        precision: Option<crate::domain::metrics::Precision>,
+        recall: Option<crate::domain::metrics::Recall>,
+        sample_count: SampleCount,
+        calculated_at: Timestamp,
+    },
+    ApplicationFScoreCalculated {
+        session_id: SessionId,
+        application_id: ApplicationId,
+        model_version: ModelVersion,
+        f_score: crate::domain::metrics::FScore,
+        precision: Option<crate::domain::metrics::Precision>,
+        recall: Option<crate::domain::metrics::Recall>,
+        sample_count: SampleCount,
+        calculated_at: Timestamp,
     },
 
     // User Events
     UserCreated {
         user_id: UserId,
         email: EmailAddress,
         display_name: Option<DisplayName>,
-        created_at: DateTime<Utc>,
+        created_at: Timestamp,
     },
     UserActivated {
         user_id: UserId,
-        activated_at: DateTime<Utc>,
+        activated_at: Timestamp,
     },
     UserDeactivated {
         user_id: UserId,
         reason: Option<ChangeReason>,
-        deactivated_at: DateTime<Utc>,
+        deactivated_at: Timestamp,
     },
 }
 
 impl DomainEvent {
     /// Get the timestamp of when this event occurred
-    pub fn occurred_at(&self) -> DateTime<Utc> {
+    pub fn occurred_at(&self) -> Timestamp {
         match self {
             DomainEvent::SessionStarted { started_at, .. } => *started_at,
             DomainEvent::SessionEnded { ended_at, .. } => *ended_at,
@@ -125,6 +146,8 @@ impl DomainEvent {
             DomainEvent::VersionChanged { changed_at, .. } => *changed_at,
             DomainEvent::VersionUsageRecorded { recorded_at, .. } => *recorded_at,
             DomainEvent::VersionDeactivated { deactivated_at, .. } => *deactivated_at,
+            DomainEvent::FScoreCalculated { calculated_at, .. } => *calculated_at,
+            DomainEvent::ApplicationFScoreCalculated { calculated_at, .. } => *calculated_at,
             DomainEvent::UserCreated { created_at, .. } => *created_at,
             DomainEvent::UserActivated { activated_at, .. } => *activated_at,
             DomainEvent::UserDeactivated { deactivated_at, .. } => *deactivated_at,
@@ -146,7 +169,7 @@ mod tests {
 
     #[test]
     fn test_event_timestamp_extraction() {
-        let now = Utc::now();
+        let now = Timestamp::now();
         let session_id = SessionId::generate();
         let user_id = UserId::generate();
 

src/domain/commands/version_commands.rs

@@ -0,0 +1,32 @@
+//! F-score tracking and analytics domain types
+//!
+//! This module provides type-safe F-score calculation and tracking functionality
+//! following type-driven development principles for precision/recall metrics.
+
+pub mod constants;
+pub mod core_metrics;
+pub mod counts;
+pub mod data_point;
+pub mod demo_data;
+pub mod demo_types;
+pub mod durations;
+pub mod errors;
+pub mod performance;
+pub mod sample_count;
+pub mod time_period;
+pub mod timestamp;
+pub mod trend;
+pub mod ui_types;
+pub mod values;
+
+// Re-export commonly used types
+pub use core_metrics::{Beta, ConfidenceLevel, FScore, Precision, Recall};
+pub use counts::{ApplicationCount, DataPointCount, ModelCount};
+pub use data_point::FScoreDataPoint;
+pub use errors::MetricsError;
+pub use performance::{PerformanceAssessment, PerformanceLevel, QualityRating};
+pub use sample_count::{SampleConfidence, SampleCount};
+pub use time_period::{DaysBack, PointsPerDay, TimePeriod};
+pub use timestamp::{Timestamp, TimestampAge};
+pub use trend::{TrendAnalysis, TrendDirection, TrendMagnitude};
+pub use values::{MetricValue, PercentageChange, StabilityThreshold};