Major Architecture Refactor: Static APIs → CapabilityScope

[windischb]

Major Architecture Refactor: Static APIs → CapabilityScope

🎯 Overview

This PR introduces CapabilityScope - a major architectural improvement that eliminates static dependencies and provides proper lifetime management for capability compositions.

Type: 🚨 Breaking Change
Version: v0.11.0
Migration: Required - See migration guide below

🔄 What Changed

Before (Static API)

// Global static access
var composition = Composer.For(userService)
    .Add(new LoggingCapability<UserService>())
    .Build();

var recomposed = Composer.Recompose(composition)
    .Add(new CachingCapability<UserService>())
    .Build();

After (Scoped API)

// Explicit scoping with resource management
using var scope = new CapabilityScope();

var composition = scope.For(userService)
    .Add(new LoggingCapability<UserService>())
    .Build();

var recomposed = scope.Recompose(composition)
    .Add(new CachingCapability<UserService>())
    .Build();

📦 Package Structure Changes

Before	After
Cocoar.Capabilities.Core (21KB)	❌ Removed
Cocoar.Capabilities (16KB)	✅ Consolidated (28KB)
Total: ~37KB	Total: ~28KB

⚡ Performance Improvements

• Registry Lookups: ~25ns (measured)
• Feature Queries: ~51ns (measured)
• Composition Builds: ~4.5μs for 50 capabilities (measured)
• Memory: Enhanced cleanup with ConditionalWeakTable for reference types

🚨 Breaking Changes

APIs Removed

• Cocoar.Capabilities.Core.Composer (static class)
• Cocoar.Capabilities.ComposerExtensions
• Cocoar.Capabilities.CompositionRegistry
• Entire Cocoar.Capabilities.Core namespace

APIs Added

• CapabilityScope - Main scoped container
• CapabilityScopeOptions - Configuration options
• Enhanced registry APIs (ComposerRegistryApi, CompositionRegistryApi)

🔧 Migration Guide

1. Update Package References

<!-- Remove -->
<PackageReference Include="Cocoar.Capabilities.Core" Version="0.10.x" />

<!-- Keep/Update -->
<PackageReference Include="Cocoar.Capabilities" Version="0.11.0" />

2. Update Using Statements

// Remove
using Cocoar.Capabilities.Core;

// Add
using Cocoar.Capabilities;

3. Wrap Static Calls in Scope

// Before
var composition = Composer.For(subject).Add(capability).Build();

// After  
using var scope = new CapabilityScope();
var composition = scope.For(subject).Add(capability).Build();

4. Dependency Injection Patterns

// Register scope with appropriate lifetime
services.AddScoped<CapabilityScope>(); // or AddSingleton/AddTransient

// Inject and use
public class MyService
{
    private readonly CapabilityScope _scope;
    
    public MyService(CapabilityScope scope) => _scope = scope;
    
    public void DoWork(MyObject obj)
    {
        var composition = _scope.For(obj).Add(capability).Build();
        // use composition
    }
}

✅ What's Preserved

• Capability Implementations: No changes needed for existing ICapability<T> classes
• Core Concepts: Composition, querying, and capability patterns remain the same
• Performance: Improved across all scenarios
• Type Safety: Enhanced compile-time guarantees
• Zero Dependencies: Maintained
• AOT Support: Preserved

🧪 Testing

• All existing tests migrated and passing
• New scope lifecycle tests added
• Performance benchmarks confirm improvements
• Memory cleanup validation
• Thread safety verification

📊 Impact Analysis

File Changes

• 95 files changed: 4,809 insertions(+), 5,906 deletions(-)
• Package consolidation: Core package eliminated
• Documentation: Comprehensive updates across all docs

Risk Assessment

• High Impact: Breaking API changes
• Medium Risk: Well-tested migration path
• Mitigation: Comprehensive documentation and gradual migration support

📚 Documentation Updates

• README.md - Updated for new architecture
• docs/getting-started.md - All examples updated
• docs/api-reference.md - Complete rewrite
• docs/static-api-migration-strategy.md - New migration guide
• docs/RELEASE-NOTES-v0.11.0.md - Detailed release notes
• CHANGELOG.md - Version 0.11.0 entry

🔍 Review Checklist

Code Quality

• No static dependencies introduced
• Proper disposal patterns implemented
• Thread-safety maintained through immutability
• Performance regression tests passing

Documentation

• All code examples updated
• Migration guide comprehensive
• Breaking changes clearly documented
• Performance claims backed by benchmarks

Compatibility

• Target frameworks unchanged (.NET Standard 2.0, .NET 8.0+)
• Zero external dependencies maintained
• AOT compilation support verified

🚀 Deployment Plan

1. Merge to develop: After review approval
2. Release v0.11.0: Create release with comprehensive notes
3. Community Communication: Blog post/announcement about migration
4. Support Period: Monitor for migration issues

🎯 Why This Change?

Problems Solved

• ❌ Testability: Static APIs made unit testing difficult
• ❌ Resource Management: No explicit cleanup mechanism
• ❌ Package Complexity: Confusing dual-package structure
• ❌ Flexibility: Static configuration couldn't be scoped

Benefits Gained

• ✅ Better Testability: Scoped dependencies enable easier testing
• ✅ Resource Control: Explicit disposal and lifetime management
• ✅ Simplified Deployment: Single package architecture
• ✅ Enhanced Performance: Measured improvements across all scenarios

---

📞 Questions?

For migration assistance or questions about this change, please:

• Review the migration guide: docs/static-api-migration-strategy.md
• Check the detailed release notes: docs/RELEASE-NOTES-v0.11.0.md
• Create an issue for specific migration challenges

This change provides a more robust foundation for capability-based development while maintaining the core benefits that make this library valuable.