Differentiate boolean defaults from explicitly set values in server config

[bashandbone]

Description

Improve boolean flag handling to differentiate between default values and user-set values.

Current State

• File: server.py:166
• Boolean flags can all be boolean
• Can't distinguish default False from user-set False
• Ambiguity in configuration merging

Problem

When a boolean is False, we can't tell:

• Is it the default value?
• Did the user explicitly set it to False?

This matters for:

• Configuration inheritance
• Environment variable override detection
• Telemetry (what did user configure vs defaults)

Possible Solutions

Option 1: Use Optional[bool]

enable_feature: bool | None = None  # None = not set, True/False = set

Option 2: Use Unset Sentinel

from typing import Literal
enable_feature: bool | Literal[Unset] = Unset

Option 3: Separate Tracking

enable_feature: bool = False
_feature_explicitly_set: bool = False

Recommendation

Use Unset sentinel (related to issue #94) for consistency with the broader configuration system.

Impact

• Better configuration merging
• Clearer telemetry
• More predictable behavior

Source

• File: server.py:166
• Branch: 003-our-aim-to

[github-actions]

Claude finished @bashandbone's task —— View job

---

Analysis Complete

I've analyzed the boolean configuration issue and reviewed the proposed solutions against the codebase patterns and pydantic-settings best practices.

---

Current State Analysis

Location: The issue references server.py:166, but the actual boolean flags are in src/codeweaver/config/settings.py:626-665 in the CodeWeaverSettings class:

• enable_background_indexing: bool = True
• enable_telemetry: bool = True
• enable_health_endpoint: bool = True
• enable_statistics_endpoint: bool = True
• enable_settings_endpoint: bool = True
• enable_version_endpoint: bool = True
• allow_identifying_telemetry: bool = False
• enable_ai_intent_analysis: bool = False
• enable_precontext: bool = False

Problem: When any of these fields have value False, the system cannot distinguish:

1. Is it the default value?
2. Did the user explicitly set it to False via config file or environment variable?

This ambiguity impacts:

• Configuration inheritance and merging
• Telemetry (understanding user preferences vs defaults)
• Environment variable override detection
• Future hot-reload functionality (issue Improve configuration state tracking (Unset values) and hot reload #94)

---

Solution Analysis

✅ Recommended: Option 2 - Unset Sentinel Pattern

Why this is the best choice:

1. Already implemented in the codebase: src/codeweaver/core/types/sentinel.py:115-121 defines both a Unset class and UNSET instance
2. Already imported in settings.py: Line 83 shows from codeweaver.core.types.sentinel import UNSET, Unset
3. Aligns with issue Improve configuration state tracking (Unset values) and hot reload #94: The broader configuration tracking system already plans to use Unset
4. Constitutional compliance: Follows "Proven Patterns" principle by using established project patterns
5. Type-safe: Works well with pydantic's type system
6. Clear semantics: UNSET is more explicit than None about intent

Implementation pattern:

enable_feature: bool | Unset = UNSET

# Then check:
if settings.enable_feature is UNSET:
    # Use default logic or inherit from parent config
elif settings.enable_feature:
    # User explicitly enabled
else:
    # User explicitly disabled

Pydantic-settings compatibility:

• Works with exclude_unset=True in serialization
• Can be validated and coerced properly
• Already has serialization support in the existing Sentinel base class

---

⚠️ Option 1 - Optional[bool] / bool | None

Pros:

• Standard Python idiom
• Native pydantic-settings support
• Simple to understand

Cons:

• None is semantically ambiguous (could mean "unset" or "disabled")
• Breaks if None has semantic meaning elsewhere
• Less explicit than a sentinel value
• Not aligned with issue Improve configuration state tracking (Unset values) and hot reload #94's approach

Verdict: Acceptable but not preferred given existing Unset infrastructure

---

❌ Option 3 - Separate Tracking Fields

Pros:

• Explicit tracking of what was set

Cons:

• Violates "Simplicity Through Architecture" principle
• Doubles the number of fields
• Error-prone (fields can get out of sync)
• Maintenance burden
• Not aligned with project patterns

Verdict: Not recommended

---

Implementation Recommendation

Approach: Adopt the Unset sentinel pattern for all boolean configuration flags

Estimated Difficulty: Low-Medium ⭐⭐⭐☆☆

Scope:

1. Update 9 boolean fields in CodeWeaverSettings to use bool | Unset = UNSET
2. Update any code that checks these booleans to handle UNSET case
3. Update TypedDict representations in config/types.py:215-243
4. Add tests for configuration merging with unset values
5. Update documentation/docstrings

Estimated Impact:

• Files to modify: 3-5 (settings.py, types.py, potentially server.py, telemetry code)
• Lines of code: ~50-100
• Breaking changes: None if defaults are handled properly
• Test coverage: Need integration tests for config inheritance

Benefits:

• ✅ Distinguishes defaults from explicit user choices
• ✅ Enables proper config inheritance/merging
• ✅ Better telemetry data (understand user preferences)
• ✅ Supports future hot-reload (issue Improve configuration state tracking (Unset values) and hot reload #94)
• ✅ Consistent with broader project direction
• ✅ Type-safe and explicit

---

Related Issues

• Improve configuration state tracking (Unset values) and hot reload #94: "Improve configuration state tracking (Unset values) and hot reload" - This issue is directly related and proposes the same Unset approach across all configuration
• Flatten configuration structure for simpler environment variables #92: "Flatten configuration structure" - May impact which fields need tracking
• Convert provider TypedDicts to Pydantic models #93: "Convert provider TypedDicts to Pydantic models" - Related config system improvements

Recommendation: Consider implementing this as part of #94's broader configuration improvements rather than in isolation.

---

Next Steps

If you'd like me to implement this change:

1. I can update the boolean fields to use bool | Unset
2. Add handling for the UNSET case in relevant code paths
3. Update TypedDicts and type annotations
4. Add appropriate tests

Let me know if you'd like me to proceed with implementation or if you have questions about the analysis!

--- | Branch: claude/issue-113-20251119-2054