[DI Phase 6] Cleanup, registry simplification, and v0.4 breaking changes

[bashandbone]

Phase 6: Cleanup, Deprecation & Breaking Changes

Parent Epic: #116
Depends On: #120 (Advanced Features)
Target: v0.3 Late / v0.4 Prep
Risk Level: Low

Finalize migration, deprecate old patterns, simplify/eliminate registry, and prepare for v0.4 breaking changes in the clean monorepo structure.

Strategic Context

After complete transformation:

• ✅ Phases 1-2: DI system working, dependencies broken
• ✅ Phase 3: Clean monorepo with 9 packages
• ✅ Phases 4-5: pydantic-ai + advanced features
• ✅ Now: Cleanup and prepare for v0.4

Goals

• Deprecate old pattern with warnings
• Simplify registry to thin layer (or eliminate entirely)
• Complete documentation overhaul
• Establish performance baselines
• Prepare for v0.4 breaking changes

Implementation Checklist

Deprecation

Add warnings to old patterns:

• Add deprecation warnings to manual registry access
• Add deprecation warnings to direct provider instantiation
• Update all remaining usages to DI
• Migration guide published
• Support for user questions

Example warning:

# Old pattern still works but warns
def get_provider_registry():
    warnings.warn(
        "Manual registry access is deprecated. Use DI instead. "
        "See migration guide: https://docs.codeweaver.dev/di-migration",
        DeprecationWarning,
        stacklevel=2
    )
    # Still works for backward compat

Registry Simplification

Decision: Simplify or eliminate?

Option A: Simplify to thin layer

# packages/codeweaver-core/registry.py
class ProviderRegistry:
    """Thin registration layer over DI."""
    
    def register_provider(self, name, cls):
        """Register provider class."""
        self._classes[name] = cls
    
    def get_provider_class(self, name):
        """Get provider class."""
        return self._classes[name]
    
    # NO instantiation logic - that's in DI factories!

Option B: Eliminate entirely

# DI container IS the registry
container.register(
    EmbeddingProvider,
    factory=get_embedding_provider,
    singleton=True
)

Recommendation from analysis: Option B - Let DI replace registry

Tasks:

• Decide: simplify or eliminate
• Remove duplicate code
• Optimize registry performance (if keeping)
• Update registry tests
• Document new architecture

Documentation Overhaul

Complete docs:

• Architecture docs updated
  • DI architecture explanation
  • Monorepo structure guide
  • Package dependency graph
• Migration guide finalized
  • Old pattern → DI pattern examples
  • Import path changes
  • Testing changes
• Best practices guide
  • When to use DI
  • Custom provider creation
  • Testing with DI
• API reference complete
  • All DI APIs documented
  • All package APIs documented
• Tutorial videos/guides (optional)

Performance & Validation

Final validation:

• Final performance benchmarking
  • DI overhead measured
  • End-to-end performance
  • Comparison with v0.1
• Memory profiling
  • Container memory usage
  • Provider instance memory
  • Total system memory
• Load testing
  • Concurrent request handling
  • Provider pool behavior
  • Resource cleanup
• Production readiness checklist
  • All tests passing
  • Type checking passing
  • No circular dependencies
  • Documentation complete

Breaking Change Preparation (v0.4)

Plan for v0.4:

• Document v0.4 breaking changes
  • Remove manual registry access
  • Require DI-based initialization
  • Update import paths (if needed)
• Communicate migration timeline
  • Announce deprecation schedule
  • Provide 12+ month migration period
  • Offer migration assistance
• Create migration automation tools (if feasible)
  • Script to convert old imports
  • Code modernization tools
  • Test migration helpers

Monorepo Context

Registry simplification in monorepo:

If keeping registry:

packages/codeweaver-core/
  registry/
    __init__.py
    thin_registry.py  # Minimal registration only

If eliminating registry:

packages/codeweaver-core/
  di/
    __init__.py
    container.py     # Container IS the registry
    # No separate registry package!

Package cleanup:

• Remove unnecessary cross-package imports
• Consolidate duplicated logic
• Optimize package boundaries

Related Issues to Close/Update

Once this phase complete:

• Close Register default services in services registry #84: Register default services → DI handles
• Close Improve EmbeddingRegistry: configurable size, dynamic sizing, persistence #100: EmbeddingRegistry improvements → Registry becomes thin layer or eliminated
• Close Integrate Indexer with services registry and implement persistence loading #103: Indexer service integration → DI replaces approach

Update:

• Update Implement provider system for reranker models (mirror embedding system) #109: Reranker provider system → Use DI patterns established
• Update monorepo docs with final architecture

Acceptance Criteria

• Old pattern deprecated (warnings active)
• All code uses DI internally
• Registry simplified or eliminated
• Documentation complete
• Performance validated
• Code review approved
• v0.4 breaking change plan documented
• Migration timeline communicated

Success Metrics

Technical:

• 0 uses of old pattern in new code
• Registry code reduced by 60%+ (or eliminated)
• Documentation covers 100% of DI APIs
• Performance within 5% of baseline

User experience:

• Clear migration path documented
• Deprecation warnings helpful
• 12+ month migration period announced
• Automation tools available (if feasible)

Timeline for v0.4 Breaking Changes

Recommended schedule:

v0.3 (This phase):

• Old pattern deprecated with warnings
• DI fully working and documented
• Migration guide published

v0.3.x (12+ months):

• Support both patterns
• Help users migrate
• Collect feedback

v0.4 (After 12+ months):

• Remove old pattern
• DI-only codebase
• Clean, simple architecture

Benefits After Complete Transformation

For developers:

• ✅ 60-70% less boilerplate
• ✅ 75% fewer circular dependencies
• ✅ Clean monorepo with 9 packages
• ✅ Simple, FastAPI-like DI
• ✅ Easy to test and extend

For users:

• ✅ Faster builds (monorepo)
• ✅ Lighter installs (package selection)
• ✅ Better performance
• ✅ Clear architecture

For codebase:

• ✅ No circular dependencies
• ✅ Clean package boundaries
• ✅ Scales to 100+ providers
• ✅ Maintainable long-term

Reference

• Planning: plans/DI_IMPLEMENTATION_CHECKLIST.md (Phase 5 section)
• Migration strategy: plans/dependency-injection-architecture-plan.md
• Monorepo structure: [Monorepo Phase 3] Organize into clean package structure (9 packages) #204
• Integrated strategy: INTEGRATED_DI_MONOREPO_STRATEGY.md

Connection to Integrated Strategy

This phase completes the transformation:

• Week 1: DI foundation ([DI Phase 1] Foundation + monorepo prep (tokenizers, daemon, SearchResult) #117)
• Week 2: DI integration, break dependencies ([DI Phase 2] Core migration - Breaking 75% of circular dependencies #118)
• Week 3: Monorepo structure ([Monorepo Phase 3] Organize into clean package structure (9 packages) #204)
• Weeks 4-6: Advanced features ([DI Phase 4] pydantic-ai integration (agents + data sources) #119, [DI Phase 5] Advanced features (health, telemetry, plugins) #120)
• This phase: Final cleanup and v0.4 prep

Total transformation: 2-3 weeks core + 3-4 weeks advanced = 5-7 weeks complete

Result:

• ✅ Clean, modern architecture
• ✅ Scales to future growth
• ✅ Maintainable long-term
• ✅ No technical debt

[github-actions]

Claude finished @bashandbone's task —— View job

---

Analysis Complete: Phase 5 Cleanup & Deprecation ✅

This is Phase 5 of a 5-phase dependency injection migration (#116) targeting v0.3 Late. I've completed a thorough analysis of the issue, codebase, and related dependencies.

---

Key Findings

🔴 Critical Blockers

1. Missing DI Planning Documents

The issue references five planning documents that do not exist in the repository:

• plans/DI_IMPLEMENTATION_CHECKLIST.md ❌
• plans/dependency-injection-architecture-plan.md ❌
• plans/DI_ARCHITECTURE_SUMMARY.md ❌
• plans/DI_ARCHITECTURE_DIAGRAMS.md ❌
• plans/DI_PROVIDER_EXAMPLES.md ❌

Impact: Phase 5 cannot proceed without understanding the architectural vision from Phases 1-4.

2. Phase 4 Dependency Not Met

• Issue states "Depends On: [DI Phase 5] Advanced features (health, telemetry, plugins) #120" (Phase 4: Advanced Features)
• Phase 4 is still open with all checkboxes unchecked
• Recommendation: Block this issue until [DI Phase 5] Advanced features (health, telemetry, plugins) #120 is completed

---

Current Architecture Analysis

Registry System (1,508 lines in src/codeweaver/common/registry.py)

Three Core Registries:

• ProviderRegistry - Manages 40+ provider implementations across 6 types
• ModelRegistry - Stores embedding/reranking model capabilities
• ServicesRegistry - Tracks available services and features

Usage Scope: Found in 9 files across the codebase

• Heavy singleton pattern with lazy initialization
• Repetitive provider registration methods (opportunity for 60-70% reduction)
• Multiple instance caches per provider type

Related Systems:

• Chunker registry (src/codeweaver/engine/chunker/registry.py)
• Grammar registry (src/codeweaver/semantic/grammar.py)
• AST pattern registry (src/codeweaver/semantic/ast_grep.py)

---

Related Issues Analysis

Issue	Title	Status	Impact
#116	[EPIC] DI Migration	OPEN	Parent epic - defines strategy
#120	Phase 4: Advanced Features	OPEN	BLOCKING - must complete first
#84	Register default services	OPEN	Will be obsoleted by DI
#100	EmbeddingRegistry improvements	OPEN	Registry becomes thin layer
#103	Indexer service integration	OPEN	DI replaces approach

---

Phase 5 Checklist Assessment

Deprecation (🔴 Blocked)

• Add deprecation warnings → Blocker: Old pattern not yet replaced by DI
• Update all remaining usages → Needs: Migration guide (doesn't exist)
• Migration guide published → Missing: No guide exists
• Support for user questions → Unclear: External users vs internal only?

Registry Cleanup (🟡 Depends on Phases 1-4)

• Simplify registry (thin layer over DI) → Scope: 1,508 lines → adapter layer
• Remove duplicate code → Opportunity: 60-70% reduction potential
• Optimize registry performance → Baseline: Needs current metrics
• Registry tests updated → Dependencies: New DI system must exist

Documentation Overhaul (🟡 Can start planning)

• Architecture docs updated → Base: ARCHITECTURE.md exists (comprehensive)
• Migration guide finalized → Status: Doesn't exist yet
• Best practices guide → Status: Doesn't exist yet
• API reference complete → Current: Docstrings only, no standalone docs

Performance & Validation (🟡 Depends on DI implementation)

• Final performance benchmarking → Needs: Pre-DI baseline metrics
• Memory profiling → Target: Within 5% of baseline (per epic [EPIC] DI + Monorepo: Unified architecture transformation #116)
• Load testing → Context: MCP server under load
• Production readiness checklist → Depends: All above items

v0.4 Breaking Changes (🟢 Can start planning)

• Document v0.4 breaking changes → Timeline: 12+ months migration period
• Communicate migration timeline → Question: When is v0.4 target?
• Create migration automation tools → Feasibility: TBD

---

Recommendations

Immediate Actions

1. Apply Labels 🏷️

   • blocked - Waiting on [DI Phase 5] Advanced features (health, telemetry, plugins) #120 completion
   • dependency-injection - Core topic
   • epic - Part of DI migration epic
   • architecture - Fundamental change
   • refactor - Major restructuring
   • migration - Breaking changes planned
   • documentation - Significant docs work

2. Update Issue Status 📋

   • Convert to Draft or mark as Blocked
   • Add note that Phase 4 must complete first
   • Consider closing and reopening when Phase 4 is done

3. Create Phase Tracking 📊

   • Add phase completion checkboxes to epic [EPIC] DI + Monorepo: Unified architecture transformation #116
   • Document what "complete" means for each phase
   • Track which phase the project is currently in

Planning Phase (Can Start Now)

1. Create DI Planning Documents 📝

   • I can help create these documents:
     • DI architecture overview
     • Implementation checklist with detailed phase breakdowns
     • Code examples (before/after migration patterns)
     • Architecture diagrams
   • Location: plans/ directory or docs/architecture/

2. Establish Performance Baselines 📈

   • Profile current registry system:
     • Initialization time
     • Memory usage
     • Provider instantiation overhead
     • Lookup performance
   • Document for comparison against DI implementation

3. Document Current Usage Patterns 🔍

   • Create inventory of all registry usage
   • Categorize by migration complexity
   • Identify edge cases requiring special handling

Implementation Phase (After Phase 4)

Estimated Timeline: 10-12 weeks

Weeks 1-2: Preparation

• Finalize DI planning documents
• Review Phase 1-4 implementations
• Create migration guide template
• Set up deprecation warning infrastructure

Weeks 3-4: Deprecation Rollout

• Add DeprecationWarning to old registry methods
• Create migration examples for each usage pattern
• Update internal usage first (eating our own dog food)
• Monitor deprecation warnings in CI

Weeks 5-6: Registry Simplification

• Refactor ProviderRegistry to thin DI adapter
• Refactor ModelRegistry to thin DI adapter
• Refactor ServicesRegistry to thin DI adapter
• Update all tests to use DI overrides

Weeks 7-8: Documentation

• Update ARCHITECTURE.md with DI section
• Complete migration guide with examples
• Write best practices guide
• Generate API reference docs

Weeks 9-10: Validation & v0.4 Prep

• Performance benchmarking (target: within 5% of baseline)
• Memory profiling
• Load testing
• Document v0.4 breaking changes
• Create migration automation (if feasible)

---

Code Locations Requiring Updates

High Priority (Direct Registry Usage)

• src/codeweaver/server.py:91-98 - Registry lazy imports
• src/codeweaver/app_bindings.py - Application bindings
• src/codeweaver/common/registry.py - Entire file (1,508 lines)
• src/codeweaver/providers/vector_stores/base.py - Provider registration
• src/codeweaver/providers/embedding/capabilities/__init__.py - Capability registration

Medium Priority (Semantic Registries)

• src/codeweaver/semantic/grammar.py - Grammar registry
• src/codeweaver/semantic/ast_grep.py - AST pattern registry
• src/codeweaver/semantic/node_type_parser.py - Node type registry
• src/codeweaver/engine/chunker/registry.py - Chunker strategy registry

Related Files

• src/codeweaver/main.py - Server initialization
• src/codeweaver/semantic/__init__.py - Semantic module exports
• src/codeweaver/semantic/classifier.py - Classification registry

---

Questions for Issue Author

1. Phase Tracking: What is the current status of Phases 1-4? Which phase is the project in now?

2. Planning Documents: Would you like me to create the referenced planning documents? If they exist elsewhere (different branch, private docs), please share the location.

3. Issue Lifecycle: Should this issue be:

   • Converted to Draft until Phase 4 completes?
   • Marked as Blocked with a dependency on [DI Phase 5] Advanced features (health, telemetry, plugins) #120?
   • Kept open for planning work that can proceed now?

4. External Users: Are there external users/adopters of CodeWeaver who need migration support? This affects:

   • Migration timeline
   • Documentation depth
   • Backward compatibility requirements
   • Communication strategy

5. v0.4 Timeline: What's the target date for v0.4 release? The epic mentions "12+ months migration period" - when does that start?

6. Documentation Location: Where should migration guides and best practices live?

   • MkDocs site (docs/ directory)?
   • GitHub wiki?
   • Inline in ARCHITECTURE.md?
   • Separate MIGRATION.md?

7. Definition of Done: What are the acceptance criteria for considering Phase 5 "complete"? Should we add specific metrics (e.g., "95% of registry usage migrated")?

---

Constitutional Compliance Check

Principle	Status	Notes
I. AI-First Context	✅ Pass	Self-documenting DI dependencies improve AI understanding
II. Proven Patterns	✅ Pass	FastAPI DI is battle-tested
III. Evidence-Based Development	⚠️ Warning	Missing planning docs and Phase 1-4 evidence
IV. Testing Philosophy	⚠️ Warning	No test strategy documented for migration
V. Simplicity Through Architecture	✅ Pass	DI reduces complexity long-term

Verdict: Issue is constitutionally sound in concept, but needs evidence (planning docs, phase completion) before proceeding.

---

Suggested Next Steps

Option 1: Start Planning Now

• I create DI planning documents
• Establish performance baselines
• Document current registry patterns
• Keep issue open for planning work

Option 2: Block Until Phase 4

• Mark issue as blocked
• Convert to draft
• Reopen when Phase 4 ([DI Phase 5] Advanced features (health, telemetry, plugins) #120) is complete
• Focus team effort on Phase 4

Option 3: Hybrid Approach

• Keep issue open but labeled blocked
• Do planning work in parallel with Phase 4
• Start implementation only after Phase 4 completes
• Use this issue to track planning progress

My Recommendation: Option 3 (Hybrid) - This maximizes forward progress while respecting dependencies.

---

Offer to Help

I can assist with:

• ✅ Creating the missing DI planning documents
• ✅ Drafting migration guide templates
• ✅ Analyzing specific registry usage patterns in detail
• ✅ Proposing deprecation warning messages
• ✅ Reviewing Phase 1-4 code (if implemented)
• ✅ Writing architecture diagrams (Mermaid/PlantUML)

Just let me know what would be most helpful!

---