Improve configuration state tracking (Unset values) and hot reload

[bashandbone]

Description

Two related improvements to types.py for better state tracking and configuration management.

1. Replace Defaults with Unset (types.py:54)

Replace most default values with Unset to better track user-set vs default values.

Current Problem

• Can't distinguish between user-set values and defaults
• Telemetry and configuration merging is ambiguous

Implementation Challenges

• Need to ensure Unset isn't passed to places that don't accept it
• Consider modifying Pydantic serialization to convert Unset → None/missing
• Keep Unset for telemetry serialization

2. Add Hot Reload with Mid-Request Handling (types.py:170)

Implement hot reload for configuration changes with proper mid-request state management.

Requirements

• Detect configuration changes
• Handle ongoing requests gracefully
• Avoid disrupting active operations
• Queue or defer config application

Considerations

• Thread safety for concurrent requests
• Rollback mechanism for bad configs
• Logging and observability

Source

• Files: types.py:54, types.py:170
• Branch: 003-our-aim-to

[github-actions]

Claude finished @bashandbone's task —— View job

---

Issue Analysis: Configuration State Tracking & Hot Reload

Summary

This issue proposes two related improvements to CodeWeaver's configuration system:

1. Replace defaults with Unset - Better track user-configured vs default values
2. Add hot reload - Detect and apply config changes without server restart

Both proposals are well-founded and align with the Project Constitution. I've completed a comprehensive analysis below.

---

Context & Related Work

Related Issues:

• Flatten configuration structure for simpler environment variables #92: "Flatten configuration structure for simpler environment variables" - Highly related, should be coordinated
• External projects show strong demand for hot reload functionality

Current Implementation:

• Configuration system uses pydantic-settings with hierarchical TOML/YAML/JSON support
• Unset sentinel type already exists (src/codeweaver/core/types/sentinel.py:115-121)
• watchfiles library already in dependencies for background indexing
• Telemetry system uses _telemetry_keys() methods for anonymized data collection
• Line 280 in types.py has TODO: reload: bool = False # TODO: We should add it, but we need to manage handling it mid-request.

---

Analysis: Proposal #1 - Replace Defaults with Unset

Current Problem

Most settings use concrete defaults (e.g., port: PositiveInt = 9328), making it impossible to distinguish:

• User explicitly set port=9328
• User never configured port (defaulted to 9328)

Benefits

1. Better Telemetry: Track which settings users actually configure
2. Config Merging: Properly merge hierarchical configs (env vars → TOML → defaults)
3. Change Detection: Know what changed for hot reloading
4. Debugging: Help users understand configured vs defaulted values

Implementation Challenges

Challenge 1: Pydantic Serialization

• model_dump() used throughout (lines 694, 776, 796, 800 in settings.py)
• Need custom serializer: Unset → None for external use, preserve for telemetry

Solution: Pydantic serialization modes:

# For API/external - omit Unset values
model_dump(mode='python', exclude_unset=True)

# For telemetry - preserve Unset
model_dump(context={'preserve_unset': True})

Challenge 2: Type System Compatibility
Code expects concrete types. Need resolution strategy:

# Option A: Properties
@property
def resolved_port(self) -> PositiveInt:
    return 9328 if self.port is UNSET else self.port

# Option B: Post-init resolution
def model_post_init(self, __context):
    if self.port is UNSET:
        self.port = 9328

Challenge 3: Scope
Not all defaults should become Unset:

• ✅ Convert: User-facing config (ports, paths, feature flags)
• ❌ Keep: Internal constants, computed values

Estimated Difficulty

Medium - ~200+ settings across multiple files, requires Pydantic customization, testing for all serialization paths

Constitutional Compliance

✅ Evidence-Based: Solves real telemetry/merging problems
✅ Proven Patterns: Pydantic supports custom serializers
⚠️ Testing Philosophy: Needs integration tests for config scenarios

---

Analysis: Proposal #2 - Add Hot Reload

Current State

• Uvicorn supports reload=True but disabled (line 280: mid-request handling TODO)
• watchfiles already used in engine/indexer.py
• Config file paths known via default_config_file_locations()

Requirements & Solutions

1. Detect Config Changes ✅ Straightforward

async for changes in watchfiles.awatch(*config_paths, debounce=1000):
    await reload_config(changes)

2. Handle Mid-Request State ⚠️ Medium Complexity

Pattern from FastAPI/Uvicorn:

async def reload_config():
    # Load and validate
    new_config = CodeWeaverSettings.from_config(path)
    
    # Wait for active requests (with timeout)
    await request_tracker.wait_for_idle(timeout=30.0)
    
    # Atomic swap
    app.state.config = new_config
    
    # Reinit dependent services
    await reinit_providers(new_config)

3. Queue/Defer Application
Options:

• Immediate: Apply after requests finish (< 30s)
• Deferred: Apply on next request
• Scheduled: Apply at intervals

Recommend: Immediate with timeout

4. Thread Safety ✅ Simple
FastMCP uses asyncio (not threads):

• Use asyncio.Lock for updates
• Atomic reference swap
• No complex locking

5. Rollback Mechanism ✅ Straightforward

try:
    new_config = CodeWeaverSettings.from_config(path)
except ValidationError as e:
    logger.error(f"Invalid config, keeping current: {e}")
    # Keep old config

6. Logging/Observability ✅ Straightforward
Existing logging infrastructure supports this with telemetry events

Implementation Phases

Phase 1: Basic Hot Reload (Easy-Medium)

async def watch_config_files():
    async for changes in watchfiles.awatch(*config_paths):
        try:
            new_settings = CodeWeaverSettings.from_config(path)
            await asyncio.sleep(1.0)  # Grace period
            app.state.settings = new_settings
            logger.info("Config reloaded")
        except Exception as e:
            logger.error(f"Reload failed: {e}")

Phase 2: Request-Aware Reload (Medium)

class RequestTracker:
    async def wait_for_idle(self, timeout: float = 30.0):
        async with asyncio.timeout(timeout):
            while self._active > 0:
                await asyncio.sleep(0.1)

Integration Points

1. FastMCP lifespan events
2. CodeWeaverSettings.from_config()
3. Provider reinitialization (may need state management)
4. Background indexer coordination

Estimated Difficulty

Medium-High

• File watching: Easy ✅
• Reload validation: Easy ✅
• Mid-request handling: Medium ⚠️
• Provider reinit: Medium-High ⚠️
• Full rollback: Medium ⚠️

Constitutional Compliance

✅ Proven Patterns: FastAPI/Uvicorn reload is battle-tested
✅ Evidence-Based: Clear user benefit
⚠️ Simplicity: Mid-request handling adds complexity
✅ Testing Philosophy: Integration tests critical

---

Recommendations

Priority Assessment

1. Proposal Fix linting errors and warnings #1 (Unset): High Priority

   • Prerequisite for Comprehensive Implementation Plan for CodeWeaver Architectural Improvements #2 (detect changes)
   • Improves telemetry immediately
   • Aligns with Flatten configuration structure for simpler environment variables #92
   • Recommend: Implement first

2. Proposal Comprehensive Implementation Plan for CodeWeaver Architectural Improvements #2 (Hot Reload): Medium Priority

   • Development quality-of-life
   • More complex
   • Recommend: Start basic, iterate

Implementation Order

Phase 1: Unset for user-facing settings
  ├─ Start with CodeWeaverSettings
  ├─ Add Pydantic serializers
  └─ Update telemetry tracking

Phase 2: Basic config watching  
  ├─ Watch files with watchfiles
  ├─ Reload and validate
  └─ Simple grace period

Phase 3: Enhanced reload
  ├─ Request tracking
  ├─ Proper rollback
  └─ Comprehensive logging

Coordination with #92

Issue #92 proposes flattening config structure.

Recommended sequence:

1. Flatten configuration structure for simpler environment variables #92 (Flatten structure) - Establishes stable config schema
2. Improve configuration state tracking (Unset values) and hot reload #94-1 (Unset tracking) - Adds state tracking to stable schema
3. Improve configuration state tracking (Unset values) and hot reload #94-2 (Hot reload) - Adds reload to tracked config

This minimizes rework and ensures config structure stability.

---

Suggested Labels

• ✅ configuration (already applied)
• ✅ enhancement (already applied)
• ✅ architecture (already applied)
• ➕ developer-experience (recommend adding - related to DX improvements)
• ➕ performance (optional - hot reload improves iteration speed)

---

Next Steps

What would you like me to do next?

Option A: Implement Proposal #1 (Unset tracking)

• Replace appropriate defaults with Unset
• Add custom Pydantic serializers
• Update telemetry

Option B: Implement Proposal #2 (Hot reload)

• Start with basic file watching
• Add config validation and reload
• Iterate on mid-request handling

Option C: Create detailed implementation specs

• Break down into subtasks with code examples
• Estimate each component
• Create implementation plan

Option D: Coordinate with #92 first

• Address config flattening before this work
• Then return to implement this issue

Option E: Analysis complete (current state)

• No implementation needed yet
• Use analysis for future planning

Please let me know your preference and I'll proceed accordingly!

--- | Branch: claude/issue-94-20251119-2049