Type Safety Features

A comprehensive exploration of Fugue's revolutionary type-safe distribution system and its practical implications for probabilistic programming. This tutorial demonstrates how dependent type theory principles eliminate runtime errors while preserving full statistical expressiveness, making probabilistic programs both safer and more performant.

The Type Safety Problem

Traditional probabilistic programming languages force all distributions to return f64, creating a fundamental mismatch between mathematical concepts and their computational representation. This leads to pervasive runtime errors, casting overhead, and semantic confusion.

graph TD
    A["Traditional PPL"] --> B["All distributions → f64"]
    B --> C["Runtime Errors"]
    B --> D["Casting Overhead"]  
    B --> E["Semantic Confusion"]
    B --> F["Precision Loss"]
    
    G["Fugue PPL"] --> H["Natural Return Types"]
    H --> I["bool for Bernoulli"]
    H --> J["u64 for Poisson"]
    H --> K["usize for Categorical"]
    H --> L["f64 for Normal"]
    
    I --> M["Compile-Time Safety"]
    J --> M
    K --> M
    L --> M
    
    style A fill:#ffcccc
    style G fill:#ccffcc
    style M fill:#ccffff

Traditional PPL Problems

// Demonstrates problems with traditional PPL approaches (shown for contrast)
fn traditional_ppl_problems() {
    println!("=== Traditional PPL Problems (What Fugue Solves) ===\n");

    // In traditional PPLs, everything returns f64, leading to:
    println!("❌ Traditional PPL Issues:");
    println!("   - Bernoulli returns f64 → if sample == 1.0 (awkward)");
    println!("   - Poisson returns f64 → count.round() as u64 (precision loss)");
    println!("   - Categorical returns f64 → array[sample as usize] (unsafe)");
    println!("   - Runtime type errors and casting overhead");
    println!();
}

Mathematical Foundation

Fugue's type system is grounded in dependent type theory, where each distribution $D$ is parameterized not just by its parameters $\theta$, but by its support type $\mathcal{S}$.

Formal Type System

For a distribution $D_{\theta }$ with parameters $\theta$ and support $\mathcal{S}$:

$$\text{sample}(D_{\theta }):\mathcal{S}$$

This ensures that sampling operations return values in their natural mathematical domain:

Type-Theoretic Properties

Natural Type System

Fugue eliminates the f64-everything problem by returning mathematically appropriate types:

use fugue::*;
use rand::thread_rng;
// Demonstrate Fugue's natural return types
fn natural_type_system() {
    println!("✅ Fugue's Natural Type System");
    println!("==============================\n");

    let mut rng = thread_rng();

    // Boolean decisions: Bernoulli → bool
    let fair_coin = Bernoulli::new(0.5).unwrap();
    let is_heads: bool = fair_coin.sample(&mut rng);

    // Natural conditional logic - no comparisons!
    let outcome = if is_heads {
        "Heads - you win!"
    } else {
        "Tails - try again"
    };
    println!("🪙 Coin flip: {} (type: bool)", outcome);

    // Count data: Poisson → u64
    let customer_arrivals = Poisson::new(5.0).unwrap();
    let arrivals: u64 = customer_arrivals.sample(&mut rng);

    // Direct arithmetic with counts - no casting!
    let service_time = arrivals * 10; // minutes per customer
    println!(
        "👥 Customers: {} arrivals, {}min service (type: u64)",
        arrivals, service_time
    );

    // Category selection: Categorical → usize
    let product_preferences = Categorical::new(vec![0.4, 0.35, 0.25]).unwrap();
    let choice: usize = product_preferences.sample(&mut rng);

    // Safe array indexing - guaranteed bounds safety!
    let products = ["Laptop", "Smartphone", "Tablet"];
    println!(
        "🛒 Customer chose: {} (index: {}, type: usize)",
        products[choice], choice
    );

    // Continuous values: Normal → f64 (unchanged, as expected)
    let measurement = Normal::new(100.0, 5.0).unwrap();
    let reading: f64 = measurement.sample(&mut rng);
    println!("📏 Sensor reading: {:.2} units (type: f64)", reading);

    println!();
}

Type Benefits by Distribution

Bernoulli Distributions

• Returns: bool - natural boolean logic
• Benefit: Direct conditional statements without equality comparisons
• Performance: No floating-point comparisons needed

Count Distributions (Poisson, Binomial)

• Returns: u64 - natural counting numbers
• Benefit: Direct arithmetic without casting or precision loss
• Performance: Integer operations are faster than float conversions

Categorical Distributions

• Returns: usize - natural array indices
• Benefit: Guaranteed bounds safety for array indexing
• Performance: No runtime bounds checking required

Continuous Distributions

• Returns: f64 - unchanged for appropriate domains
• Benefit: Expected behavior preserved for mathematical operations

Compile-Time Safety

Fugue's type system catches errors at compile time, eliminating entire classes of runtime failures:

use fugue::*;
use fugue::runtime::interpreters::PriorHandler;
use rand::thread_rng;
// Demonstrate compile-time type safety guarantees
fn compile_time_safety_demo() {
    println!("🛡️ Compile-Time Type Safety");
    println!("============================\n");

    // Type-safe model composition
    let data_model: Model<(bool, u64, usize, f64)> = prob!(
        let coin_result <- sample(addr!("coin"), Bernoulli::new(0.6).unwrap());
        let event_count <- sample(addr!("events"), Poisson::new(3.0).unwrap());
        let category <- sample(addr!("category"), Categorical::uniform(4).unwrap());
        let measurement <- sample(addr!("measure"), Normal::new(0.0, 1.0).unwrap());

        // Compiler enforces correct types throughout
        pure((coin_result, event_count, category, measurement))
    );

    println!("✅ Model created with strict type guarantees:");
    println!("   - coin_result: bool (no == 1.0 needed)");
    println!("   - event_count: u64 (direct arithmetic)");
    println!("   - category: usize (safe indexing)");
    println!("   - measurement: f64 (natural continuous)");

    // Execute model safely
    let mut rng = thread_rng();
    let (sample, _trace) = runtime::handler::run(
        PriorHandler {
            rng: &mut rng,
            trace: Trace::default(),
        },
        data_model,
    );

    println!(
        "📊 Sample: coin={}, events={}, category={}, value={:.3}",
        sample.0, sample.1, sample.2, sample.3
    );
    println!();
}

Type-Safe Model Composition

Models compose naturally while preserving type information throughout the computation:

Safe Array Indexing

One of the most dangerous operations in traditional PPLs is array indexing with categorical samples. Fugue makes this provably safe:

use fugue::*;
use rand::thread_rng;
// Demonstrate safe array indexing with categorical distributions
fn safe_array_indexing() {
    println!("🎯 Safe Array Indexing");
    println!("======================\n");

    let mut rng = thread_rng();

    // Define categories with natural indexing
    let algorithms = ["MCMC", "Variational Inference", "ABC", "SMC", "Exact"];
    let method_weights = vec![0.3, 0.25, 0.2, 0.15, 0.1];

    let method_selector = Categorical::new(method_weights).unwrap();

    println!("🧮 Available inference methods:");
    for (i, method) in algorithms.iter().enumerate() {
        println!("   {}: {}", i, method);
    }
    println!();

    // Sample multiple times to show safety
    for trial in 1..=5 {
        let selected_idx: usize = method_selector.sample(&mut rng);

        // This is GUARANTEED safe - no bounds checking needed!
        let chosen_method = algorithms[selected_idx];

        println!(
            "Trial {}: Selected method '{}' (index {})",
            trial, chosen_method, selected_idx
        );
    }

    println!("\n✅ All array accesses guaranteed safe by type system!");
    println!();
}

Bounds Safety Guarantee

Why This Matters

Traditional PPLs require defensive programming:

// Traditional PPL - unsafe!
let category = categorical_sample as usize;
if category < array.len() {
    return array[category];  // Still might panic due to float precision!
} else {
    return default_value;    // Defensive fallback
}

Fugue guarantees safety:

// Fugue - provably safe!
let category: usize = categorical.sample(&mut rng);
return array[category];  // Cannot panic - guaranteed by type system

Parameter Validation

Fugue validates all distribution parameters at construction time, catching invalid configurations before they can cause runtime errors:

use fugue::*;
// Demonstrate parameter validation and error handling
fn parameter_validation_demo() {
    println!("🔍 Parameter Validation");
    println!("=======================\n");

    println!("Fugue validates parameters at construction time:");
    println!();

    // Valid constructions
    match Normal::new(0.0, 1.0) {
        Ok(_) => println!("✅ Normal(μ=0.0, σ=1.0) - valid"),
        Err(e) => println!("❌ Unexpected error: {:?}", e),
    }

    match Beta::new(2.0, 3.0) {
        Ok(_) => println!("✅ Beta(α=2.0, β=3.0) - valid"),
        Err(e) => println!("❌ Unexpected error: {:?}", e),
    }

    match Categorical::new(vec![0.3, 0.4, 0.3]) {
        Ok(_) => println!("✅ Categorical([0.3, 0.4, 0.3]) - valid"),
        Err(e) => println!("❌ Unexpected error: {:?}", e),
    }

    println!();

    // Invalid constructions - caught at compile time with .unwrap()
    // or handled gracefully with pattern matching
    println!("Invalid parameter examples:");

    match Normal::new(0.0, -1.0) {
        Ok(_) => println!("✅ Normal(μ=0.0, σ=-1.0) - unexpected success"),
        Err(e) => println!("❌ Normal(μ=0.0, σ=-1.0) - {}", e),
    }

    match Beta::new(0.0, 1.0) {
        Ok(_) => println!("✅ Beta(α=0.0, β=1.0) - unexpected success"),
        Err(e) => println!("❌ Beta(α=0.0, β=1.0) - {}", e),
    }

    match Categorical::new(vec![0.5, 0.6]) {
        // Doesn't sum to 1
        Ok(_) => println!("✅ Categorical([0.5, 0.6]) - unexpected success"),
        Err(e) => println!("❌ Categorical([0.5, 0.6]) - {}", e),
    }

    println!("\n✅ All invalid parameters caught before runtime!");
    println!();
}

Validation Strategy

Fugue uses fail-fast construction with comprehensive parameter checking:

Type-Safe Observations

Observations in Fugue must match the distribution's return type, providing compile-time guarantees about data consistency:

use fugue::*;
use fugue::runtime::interpreters::PriorHandler;
use rand::thread_rng;
// Demonstrate type-safe observations with automatic type checking
fn type_safe_observations() {
    println!("🔗 Type-Safe Observations");
    println!("=========================\n");

    // Observations must match distribution return types
    let observation_model = prob!(
        // Boolean observation - must provide bool
        let _bool_obs <- observe(addr!("coin_obs"),
                                Bernoulli::new(0.7).unwrap(),
                                true); // ✅ bool type matches

        // Count observation - must provide u64
        let _count_obs <- observe(addr!("events_obs"),
                                 Poisson::new(4.0).unwrap(),
                                 5u64); // ✅ u64 type matches

        // Category observation - must provide usize
        let _category_obs <- observe(addr!("choice_obs"),
                                    Categorical::new(vec![0.2, 0.5, 0.3]).unwrap(),
                                    1usize); // ✅ usize type matches

        // Continuous observation - must provide f64
        let _continuous_obs <- observe(addr!("measurement_obs"),
                                      Normal::new(10.0, 2.0).unwrap(),
                                      12.5f64); // ✅ f64 type matches

        pure(())
    );

    println!("✅ All observations type-checked at compile time!");
    println!("   - Bernoulli observation: bool");
    println!("   - Poisson observation: u64");
    println!("   - Categorical observation: usize");
    println!("   - Normal observation: f64");

    // Execute to verify it works
    let mut rng = thread_rng();
    let (_result, trace) = runtime::handler::run(
        PriorHandler {
            rng: &mut rng,
            trace: Trace::default(),
        },
        observation_model,
    );

    println!(
        "📊 Model executed successfully with {} addresses",
        trace.choices.len()
    );
    println!();
}

Observation Type Matching

The type system ensures that observed values match the distribution's natural type:

// ✅ Type-safe observations
observe(addr!("coin"), Bernoulli::new(0.5).unwrap(), true);     // bool
observe(addr!("count"), Poisson::new(3.0).unwrap(), 5u64);     // u64  
observe(addr!("choice"), Categorical::uniform(3).unwrap(), 1usize); // usize
observe(addr!("measure"), Normal::new(0.0, 1.0).unwrap(), 2.5f64);  // f64

// ❌ These would be compile-time errors
observe(addr!("coin"), Bernoulli::new(0.5).unwrap(), 1.0);     // f64 ≠ bool
observe(addr!("count"), Poisson::new(3.0).unwrap(), 5.0);      // f64 ≠ u64
observe(addr!("choice"), Categorical::uniform(3).unwrap(), 1);  // i32 ≠ usize

Advanced Type Composition

Fugue supports complex hierarchical models with full type safety throughout the computation:

use fugue::*;
use fugue::runtime::interpreters::PriorHandler;
use rand::thread_rng;
// Demonstrate advanced type-safe model composition
fn advanced_type_composition() {
    println!("🧩 Advanced Type Composition");
    println!("============================\n");

    // Complex hierarchical model with full type safety
    let hierarchical_model = prob!(
        // Global parameters
        let success_rate <- sample(addr!("global_rate"), Beta::new(1.0, 1.0).unwrap());

        // Group-specific parameters (different types working together)
        let group_sizes <- sequence_vec((0..3).map(|group_id| {
            sample(addr!("group_size", group_id), Poisson::new(10.0).unwrap())
        }).collect());

        let group_successes <- sequence_vec(group_sizes.iter().enumerate().map(|(group_id, &size)| {
            sample(addr!("successes", group_id), Binomial::new(size, success_rate).unwrap())
        }).collect());

        // Category assignments for each group
        let group_categories <- sequence_vec((0..3).map(|group_id| {
            sample(addr!("category", group_id), Categorical::uniform(4).unwrap())
        }).collect());

        // Return complex structured result with full type safety
        pure((success_rate, group_sizes, group_successes, group_categories))
    );

    println!("🏗️ Hierarchical model structure:");
    println!("   - Global success rate: f64 (Beta distribution)");
    println!("   - Group sizes: Vec<u64> (Poisson distributions)");
    println!("   - Group successes: Vec<u64> (Binomial distributions)");
    println!("   - Group categories: Vec<usize> (Categorical distributions)");
    println!();

    // Sample from the complex model
    let mut rng = thread_rng();
    let (result, _trace) = runtime::handler::run(
        PriorHandler {
            rng: &mut rng,
            trace: Trace::default(),
        },
        hierarchical_model,
    );

    let (rate, sizes, successes, categories) = result;

    println!("📈 Sample from hierarchical model:");
    println!("   Global success rate: {:.3}", rate);

    for (i, ((&size, &success), &category)) in sizes
        .iter()
        .zip(successes.iter())
        .zip(categories.iter())
        .enumerate()
    {
        println!(
            "   Group {}: {} trials, {} successes, category {}",
            i, size, success, category
        );
    }

    println!("\n✅ Complex model composed with full type safety!");
    println!();
}

Hierarchical Type Structure

Complex models maintain precise type information at every level:

graph TD
    A["Global: f64"] --> B["Group Sizes: Vec<u64>"]
    A --> C["Group Successes: Vec<u64>"]  
    A --> D["Group Categories: Vec<usize>"]
    
    B --> E["Model: (f64, Vec<u64>, Vec<u64>, Vec<usize>)"]
    C --> E
    D --> E
    
    style A fill:#e1f5fe
    style E fill:#c8e6c9

Performance Benefits

Type safety in Fugue eliminates runtime overhead through zero-cost abstractions:

// Demonstrate performance benefits of type safety
fn performance_benefits() {
    println!("⚡ Performance Benefits");
    println!("======================\n");

    println!("Type safety eliminates runtime overhead:");
    println!();

    println!("🚫 Traditional PPL (f64 everything):");
    println!("   let coin_flip = sample(...); // Returns f64");
    println!("   if coin_flip == 1.0 {{ ... }} // Float comparison");
    println!("   let count = sample(...) as u64; // Casting overhead");
    println!("   array[sample(...) as usize] // Unsafe casting + bounds check");
    println!();

    println!("✅ Fugue (natural types):");
    println!("   let coin_flip: bool = sample(...); // Returns bool");
    println!("   if coin_flip {{ ... }} // Natural boolean");
    println!("   let count: u64 = sample(...); // Direct u64");
    println!("   array[sample(...)] // Safe usize indexing");
    println!();

    println!("🎯 Benefits:");
    println!("   ✓ Zero casting overhead");
    println!("   ✓ No floating-point comparisons for discrete values");
    println!("   ✓ Eliminated bounds checking for categorical indexing");
    println!("   ✓ No precision loss from float→int conversions");
    println!("   ✓ Compile-time error detection");
    println!();
}

Performance Analysis

Real-World Applications

Quality Control System

use fugue::*;
let quality_model = prob!(
    // Product defect rate (continuous parameter)
    let defect_rate <- sample(addr!("defect_rate"), Beta::new(1.0, 9.0).unwrap());
    
    // Number of products tested (count data)
    let products_tested <- sample(addr!("tested"), Poisson::new(100.0).unwrap());
    
    // Actual defects found (count with bounds)
    let defects_found <- sample(addr!("defects"), 
                                Binomial::new(products_tested, defect_rate).unwrap());
    
    // Inspector assignment (categorical choice)
    let inspector <- sample(addr!("inspector"), Categorical::uniform(3).unwrap());
    
    // Natural type usage throughout
    pure((defect_rate, products_tested, defects_found, inspector))
);

Medical Diagnosis System

use fugue::*;  
let diagnosis_model = prob!(
    // Prior disease probability (continuous)
    let disease_prob <- sample(addr!("prior"), Beta::new(2.0, 98.0).unwrap());
    
    // Number of symptoms (count) 
    let symptom_count <- sample(addr!("symptoms"), Poisson::new(2.5).unwrap());
    
    // Test result (boolean outcome)
    let test_positive <- sample(addr!("test"), Bernoulli::new(0.95).unwrap());
    
    // Treatment recommendation (categorical)
    let treatment <- sample(addr!("treatment"), 
                           Categorical::new(vec![0.6, 0.3, 0.1]).unwrap());
    
    pure((disease_prob, symptom_count, test_positive, treatment))
);

Production Considerations

Error Handling Strategy

use fugue::*;
// Robust parameter validation
fn create_robust_model(rate: f64, categories: Vec<f64>) -> Result<Model<(f64, usize)>, String> {
    let poisson = Poisson::new(rate)
        .map_err(|e| format!("Invalid Poisson rate {}: {}", rate, e))?;
        
    let categorical = Categorical::new(categories)
        .map_err(|e| format!("Invalid categorical weights: {}", e))?;
    
    Ok(prob!(
        let count <- sample(addr!("count"), poisson);
        let choice <- sample(addr!("choice"), categorical);
        pure((count as f64, choice))
    ))
}

Performance Optimization

Testing Your Understanding

Exercise 1: Safe Model Construction

Create a model that demonstrates all four natural return types. Ensure it:

• Uses boolean logic for decision-making
• Performs arithmetic with count data
• Safely indexes into arrays
• Handles continuous parameters

// Exercise framework for testing understanding
fn testing_framework_example() {
    println!("🧪 Testing Framework Example");
    println!("============================\n");

    let comprehensive_model = prob!(
        // Boolean decision making
        let is_premium <- sample(addr!("premium"), Bernoulli::new(0.3).unwrap());

        // Count data arithmetic
        let base_items <- sample(addr!("base_items"), Poisson::new(5.0).unwrap());
        let bonus_items = if is_premium { base_items + 2 } else { base_items };

        // Safe array indexing
        let service_tier <- sample(addr!("tier"), Categorical::new(vec![0.5, 0.3, 0.2]).unwrap());

        // Continuous parameters
        let satisfaction <- sample(addr!("satisfaction"), Beta::new(2.0, 1.0).unwrap());

        pure((is_premium, bonus_items, service_tier, satisfaction))
    );

    println!("✅ Comprehensive model demonstrates:");
    println!("   - Boolean logic: Premium account decision");
    println!("   - Count arithmetic: Items calculation with bonus");
    println!("   - Safe indexing: Service tier selection");
    println!("   - Continuous data: Customer satisfaction modeling");

    let mut rng = thread_rng();
    let (premium, items, tier, satisfaction) = runtime::handler::run(
        PriorHandler {
            rng: &mut rng,
            trace: Trace::default(),
        },
        comprehensive_model,
    )
    .0;

    let tiers = ["Basic", "Standard", "Premium"];
    println!("\n📊 Sample result:");
    println!("   Premium account: {}", premium);
    println!("   Items received: {}", items);
    println!("   Service tier: {} ({})", tiers[tier], tier);
    println!("   Satisfaction: {:.2}%", satisfaction * 100.0);
    println!();
}

Exercise 2: Parameter Validation

Write a function that attempts to create distributions with both valid and invalid parameters. Handle errors gracefully and provide meaningful error messages.

Exercise 3: Hierarchical Composition

Design a hierarchical model that combines multiple data types across different levels. Ensure type safety is maintained throughout the composition.

Key Takeaways

Core Benefits:

• ✅ Eliminated runtime type errors - impossible by construction
• ✅ Natural mathematical operations - no awkward casting or comparisons
• ✅ Guaranteed array safety - categorical indexing cannot panic
• ✅ Performance improvements - zero-cost abstractions enable optimizations
• ✅ Clear code intent - types document the mathematical structure

Further Reading

• Working with Distributions - Practical distribution usage patterns
• Building Complex Models - Advanced composition techniques
• API Reference - Complete type specifications
• Types and Programming Languages by Benjamin Pierce - Theoretical foundations
• Probabilistic Programming & Bayesian Methods for Hackers - Applied Bayesian inference