alexnodeland · alexnodeland · Sep 1, 2025 · Sep 1, 2025 · Sep 1, 2025 · Sep 1, 2025
@@ -1,84 +1,83 @@
 # Changelog
 
-## [0.3.0] - 2024-12-19 - General Improvements
-
-### 🚀 **Major Improvements**
-
-#### **Numerical Stability & Correctness**
-
-- **Fixed all distribution implementations** with proper parameter validation and overflow protection
-- **Implemented stable log-sum-exp** for SMC weight normalization
-- **Added numerical utilities module** with robust mathematical functions
-- **Enhanced error handling** with comprehensive FugueError types and validation traits
-
-#### **Theoretical Soundness**
-
-- **Proper diminishing adaptation** for MCMC following Roberts & Rosenthal (2007)
-- **Ergodicity-preserving algorithms** with mathematical guarantees
-- **Stable acceptance probability computation** using log-space comparisons
-- **Correct conditioning semantics** for probabilistic programming
-
-#### **Performance & Memory Optimization**
-
-- **Copy-on-write traces** reducing MCMC allocation overhead by ~60%
-- **Memory pooling** for efficient object reuse
-- **Optimized model execution** with reduced heap allocations
-- **Efficient weight normalization** preventing underflow/overflow
-
-#### **Enhanced Diagnostics**
-
-- **Effective sample size computation** with proper autocorrelation analysis
-- **Geweke convergence diagnostics** for single-chain assessment
-- **Statistical validation framework** against analytical solutions
-- **Comprehensive convergence monitoring** with multiple metrics
-
-#### **Production Features**
-
-- **Parameter validation** for all probability distributions
-- **Structured error handling** with context and recovery suggestions
-- **Extensive test suite** including numerical stability stress tests
-- **Complete documentation** with mathematical foundations
-
-### 🔧 **Breaking Changes**
-
-- `AdaptiveScales` removed entirely - use `DiminishingAdaptation` instead
-- Distribution constructors now return `Result<T, FugueError>` for validation
-- Enhanced `VariationalParam` with numerical stability improvements
-- Improved MCMC functions with better theoretical properties
-
-### 🚀 **New Features**
-
-- `DiminishingAdaptation` for theoretically sound MCMC adaptation
-- `log_sum_exp` and numerical utilities for stable computation
-- `CowTrace` and memory management optimizations
-- `ValidationResult` and statistical testing framework
-- Comprehensive diagnostics with `effective_sample_size_mcmc` and `geweke_diagnostic`
-
-### 📚 **Documentation**
-
-- Complete mathematical formulations for all algorithms
-- 70+ working examples with compilation verification
-- Theoretical background and convergence properties
-- Production deployment guidelines
-
-### ⚡ **Performance**
-
-- ~60% reduction in memory allocations for MCMC
-- Stable numerical computation preventing overflow/underflow
-- Optimized SMC with proper weight handling
-- Efficient trace operations with copy-on-write semantics
-
----
-
-## [0.2.0]
-
-- Basic probabilistic programming functionality
-- Simple inference algorithms
-- Monadic model composition
-- Original documentation
-
----
-
-## [0.1.0]
-
-- Initial release
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2025-09-XX
+
+### Added
+
+- Initial release of Fugue, a monadic probabilistic programming library for Rust.
+- **Core probabilistic programming framework**:
+  - `Model<A>` abstraction for composable probabilistic programs.
+  - Monadic operations: `bind`, `map`, `and_then`, `pure` for program composition.
+  - `sample`, `observe`, `factor`, `guard` primitives for probabilistic modeling.
+- **Type-safe distribution system** with natural return types:
+  - `Bernoulli` distribution returning `bool` (eliminates `== 1.0` comparisons).
+  - `Poisson` and `Binomial` distributions returning `u64` (natural counting).
+  - `Categorical` distribution returning `usize` (safe array indexing).
+  - Continuous distributions (`Normal`, `Beta`, `Gamma`, etc.) returning `f64`.
+  - 10 built-in distributions with parameter validation and numerical stability.
+- **Ergonomic macros** for probabilistic programming:
+  - `prob!` macro for Haskell-style do-notation.
+  - `plate!` macro for vectorized operations over collections.
+  - `addr!` and `scoped_addr!` macros for hierarchical addressing.
+- **Multiple inference algorithms**:
+  - MCMC: Adaptive Metropolis-Hastings with convergence diagnostics.
+  - SMC: Sequential Monte Carlo with multiple resampling methods.
+  - VI: Mean-field variational inference with ELBO optimization.
+  - ABC: Approximate Bayesian Computation with distance functions.
+- **Effect handler system**:
+  - `Handler` trait for pluggable model interpreters.
+  - 5 built-in handlers: `PriorHandler`, `ReplayHandler`, `ScoreGivenTrace`, `SafeReplayHandler`, `SafeScoreGivenTrace`.
+  - Type-safe execution preserving distribution return types.
+- **Trace system** for execution history:
+  - Complete recording of random choices and log-weights.
+  - Type-safe value access with `get_f64()`, `get_bool()`, `get_u64()`, `get_usize()`.
+  - Three-component log-weight decomposition (prior, likelihood, factors).
+- **Memory optimization**:
+  - Copy-on-write traces (`CowTrace`) for efficient MCMC proposals.
+  - Object pooling (`TracePool`) for zero-allocation inference.
+  - Efficient trace construction (`TraceBuilder`).
+- **Production features**:
+  - Comprehensive error handling with `FugueError` and error codes.
+  - Numerically stable algorithms with overflow protection.
+  - Convergence diagnostics: R-hat, effective sample size, Geweke tests.
+  - Statistical validation against analytical solutions.
+- **Documentation and examples**:
+  - Comprehensive user guide with 20+ tutorial and how-to pages.
+  - Complete API documentation with rustdoc.
+  - 14 examples covering foundation concepts, statistical modeling, and advanced patterns.
+  - 158+ doctests ensuring example correctness.
+- **Testing infrastructure**:
+  - 82+ unit tests across all modules.
+  - 9+ integration tests for end-to-end workflows.
+  - Property-based testing with `proptest`.
+  - Continuous integration with format, lint, and test enforcement.
+
+### Changed
+
+- N/A (initial release)
+
+### Deprecated
+
+- N/A (initial release)
+
+### Removed
+
+- N/A (initial release)
+
+### Fixed
+
+- N/A (initial release)
+
+### Security
+
+- N/A (initial release)
+
+[Unreleased]: https://github.com/alexandernodeland/fugue/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/alexandernodeland/fugue/releases/tag/v0.1.0
@@ -0,0 +1,187 @@
+# Contributing to Fugue
+
+Thank you for your interest in contributing to Fugue! This document provides guidelines for contributing to the project.
+
+## Quick Start
+
+```bash
+git clone https://github.com/alexandernodeland/fugue.git
+cd fugue
+cargo test --all-features
+```
+
+## Development Setup
+
+### Prerequisites
+
+- Rust 1.70+ (install via [rustup](https://rustup.rs/))
+- Git
+
+### Building and Testing
+
+```bash
+# Run all tests
+make test
+
+# Format code
+make fmt
+
+# Lint code  
+make lint
+
+# Run benchmarks
+make bench
+
+# Generate coverage report
+make coverage
+
+# Run all checks
+make all
+```
+
+Or use cargo directly:
+
+```bash
+cargo test --all-features
+cargo fmt
+cargo clippy -- -D warnings
+```
+
+## Contributing Guidelines
+
+### Issues
+
+- Use GitHub Issues for bug reports and feature requests
+- Provide clear reproduction steps for bugs
+- Include relevant code examples
+
+### Pull Requests
+
+- Fork the repository and create a feature branch from `develop`
+- **Rebase your branch** to the top of `develop` before submitting PR
+- Use **semantic commit messages** (e.g., `feat:`, `fix:`, `docs:`, `refactor:`)
+- Add tests for new functionality
+- **Ensure all CI checks pass** before requesting review
+- PRs are **squash merged** to maintain linear history
+- Update documentation as needed
+
+### Versioning
+
+- We follow [Semantic Versioning](https://semver.org/) (SemVer)
+- Breaking changes increment major version
+- New features increment minor version  
+- Bug fixes increment patch version
+
+### Code Style
+
+- Follow Rust standard formatting (`cargo fmt`)
+- Address all clippy warnings (`cargo clippy -- -D warnings`)
+- Add documentation for public APIs
+- Include examples in documentation
+
+## Project Structure
+
+```mermaid
+graph LR
+    A["🎻 Fugue<br/>Monadic Probabilistic Programming"] --> B["📦 Core Module"]
+    A --> C["🔬 Inference Module"]
+    A --> D["⚙️ Runtime Module"]
+    A --> E["🎛️ Macros Module"]
+    A --> F["⚠️ Error Module"]
+
+    B --> B1["📍 Address System<br/>addr!(), scoped_addr!()"]
+    B --> B2["📊 Distributions<br/>10 type-safe distributions"]
+    B --> B3["🧩 Model<T><br/>Monadic composition"]
+    B --> B4["🔢 Numerical<br/>Stable algorithms"]
+
+    B2 --> B2A["bool: Bernoulli"]
+    B2 --> B2B["u64: Poisson, Binomial"]
+    B2 --> B2C["usize: Categorical"]
+    B2 --> B2D["f64: Normal, Beta, Gamma, etc."]
+
+    C --> C1["🔗 MCMC<br/>Adaptive Metropolis-Hastings"]
+    C --> C2["🎯 SMC<br/>Particle filtering"]
+    C --> C3["📈 VI<br/>Mean-field approximation"]
+    C --> C4["🎲 ABC<br/>Likelihood-free inference"]
+    C --> C5["📊 Diagnostics<br/>R-hat, ESS, validation"]
+
+    D --> D1["🎭 Handler System<br/>Effect interpreters"]
+    D --> D2["📝 Trace System<br/>Execution history"]
+    D --> D3["💾 Memory Optimization<br/>Pooling & COW"]
+
+    D1 --> D1A["PriorHandler"]
+    D1 --> D1B["ReplayHandler"]
+    D1 --> D1C["ScoreGivenTrace"]
+    D1 --> D1D["Safe variants"]
+
+    E --> E1["prob!<br/>Do-notation"]
+    E --> E2["plate!<br/>Vectorization"]
+
+    F --> F1["FugueError<br/>Rich error context"]
+
+    G["📚 Documentation"] --> G1["User Guide<br/>20+ pages"]
+    G --> G2["API Reference<br/>Complete rustdoc"]
+    G --> G3["14 Examples<br/>Real-world scenarios"]
+
+    H["🧪 Testing"] --> H1["82+ Unit Tests"]
+    H --> H2["9+ Integration Tests"]
+    H --> H3["158+ Doctests"]
+    H --> H4["Property-based Tests"]
+
+    I["⚡ Benchmarks"] --> I1["MCMC Performance<br/>Adaptation & diagnostics"]
+    I --> I2["Memory Optimization<br/>Pooling & COW traces"]
+
+    style A fill:#e1f5fe
+    style B fill:#f3e5f5
+    style C fill:#e8f5e8
+    style D fill:#fff3e0
+    style E fill:#fce4ec
+    style F fill:#ffebee
+    style G fill:#f1f8e9
+    style H fill:#e3f2fd
+    style I fill:#fff8e1
+```
+
+### Directory Structure
+
+```text
+fugue/
+├── src/
+│   ├── core/                   # Core probabilistic programming abstractions
+│   │   ├── address.rs          # Hierarchical addressing system
+│   │   ├── distribution.rs     # Type-safe distributions (10 built-in)
+│   │   ├── model.rs            # Monadic Model<T> abstraction
+│   │   └── numerical.rs        # Numerically stable algorithms
+│   ├── inference/              # Inference algorithms
+│   │   ├── mh.rs               # MCMC (Adaptive Metropolis-Hastings)
+│   │   ├── smc.rs              # Sequential Monte Carlo
+│   │   ├── vi.rs               # Variational Inference
+│   │   ├── abc.rs              # Approximate Bayesian Computation
+│   │   └── diagnostics.rs      # R-hat, ESS, validation
+│   ├── runtime/                # Execution engine
+│   │   ├── handler.rs          # Effect handler system
+│   │   ├── interpreters.rs     # Built-in handlers
+│   │   ├── trace.rs            # Execution history recording
+│   │   └── memory.rs           # Memory optimization (pooling, COW)
+│   ├── macros/                 # Ergonomic macros
+│   │   └── mod.rs              # prob!, plate!, addr! macros
+│   └── error.rs                # Comprehensive error handling
+├── examples/                   # 14 complete examples
+│   ├── bayesian_coin_flip.rs
+│   ├── linear_regression.rs
+│   ├── mixture_models.rs
+│   ├── hierarchical_models.rs
+│   └── ...
+├── benches/                    # Performance benchmarks
+│   ├── mcmc_benchmarks.rs      # MCMC adaptation & diagnostics
+│   └── memory_benchmarks.rs    # Memory pooling & COW traces
+├── tests/                      # Integration tests
+├── docs/                       # User guide & documentation
+│   ├── src/                    # mdBook source
+│   └── api/                    # API documentation
+└── target/                     # Build artifacts
+```
+
+## Questions?
+
+Open an issue or start a discussion on GitHub. We're happy to help!