refactor(config): replace mutable hydration with immutable ResolvedAppConfig and deprecate IConfig.set()

Architecture changes:
- Introduce immutable ResolvedAppConfig for startup-derived values
- Replace mutating hydrate_auto_append_first_prompt() with pure resolve
  functions that return values without modifying config
- Refactor _prune_unavailable_routes() to store effective routes in runtime
  state via set_failover_route() instead of mutating app_config.failover_routes
- Add DeprecationWarning to IConfig.set()/AppConfig.set() — callers should
  use model_copy(update=...) or ApplicationState instead
- Remove post-load config mutation from load_config(), from_env(), and
  ConfigurationApplicator
- Update RequestTransformPipeline to read resolved_app_config from runtime
  state with lazy fallback to resolve_app_config()
- Populate app.state.resolved_app_config during application startup

This is the first slice of a staged refactor toward immutable AppConfig +
mutable ApplicationRuntime separation.

Author: Mateusz

src/anthropic_server.py

@@ -51,6 +51,14 @@ async def create_anthropic_app_async(
 
     _register_anthropic_endpoints(app, prefix="")
     app.state.app_config = app_config
+    try:
+        from src.core.config.auto_append_first_prompt_hydration import (
+            resolve_app_config,
+        )
+
+        app.state.resolved_app_config = resolve_app_config(app_config)
+    except Exception:
+        app.state.resolved_app_config = None
 
     # Register Codebuff WebSocket endpoint if enabled
     if app_config.codebuff.enabled:

src/core/app/application_builder.py

@@ -442,6 +442,14 @@ def _create_fastapi_app(
         # Store essential state
         app.state.service_provider = service_provider
         app.state.app_config = config
+        try:
+            from src.core.config.auto_append_first_prompt_hydration import (
+                resolve_app_config,
+            )
+
+            app.state.resolved_app_config = resolve_app_config(config)
+        except Exception:
+            app.state.resolved_app_config = None
 
         # Bridge application state service methods onto FastAPI state for compatibility
         try:

src/core/cli_support/configuration_applicator.py

@@ -196,11 +196,6 @@ def apply_overrides(
 
         # Validate and apply command prefix (ensures it's never None)
         final_cfg = self._validate_and_apply_prefix(final_cfg, validate_command_prefix)
-        from src.core.config.auto_append_first_prompt_hydration import (
-            hydrate_auto_append_first_prompt,
-        )
-
-        hydrate_auto_append_first_prompt(final_cfg)
         return final_cfg
 
     def _set_auxiliary_routing_base_config_disable(

src/core/config/app_config.py

@@ -2,6 +2,7 @@
 
 import logging
 import os
+import warnings
 from collections.abc import Mapping
 from pathlib import Path
 from typing import Any, cast
@@ -161,11 +162,6 @@ def from_env(
         loader = AppConfigLoader(backend_instances_dir=BACKEND_INSTANCES_DIR)
         model = loader.load(None, environ=env, resolution=res)
         cfg = cls.model_validate(model.model_dump())
-        from src.core.config.auto_append_first_prompt_hydration import (
-            hydrate_auto_append_first_prompt,
-        )
-
-        hydrate_auto_append_first_prompt(cfg)
         return cfg
 
     def get(self, key: str, default: Any = None) -> Any:
@@ -190,7 +186,19 @@ def get(self, key: str, default: Any = None) -> Any:
             return default
 
     def set(self, key: str, value: Any) -> None:
-        """Set a configuration value (legacy convenience)."""
+        """Set a configuration value (legacy convenience).
+
+        .. deprecated::
+            ``IConfig.set()`` is deprecated.  Use ``model_copy(update=...)`` on
+            the immutable model or mutate runtime state via ``ApplicationState``
+            instead.
+        """
+        warnings.warn(
+            "IConfig.set() is deprecated; use model_copy(update=...) or mutate "
+            "runtime state via ApplicationState instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         setattr(self, key, value)
 
     def get_gcp_project_id(self) -> str | None:
@@ -214,11 +222,6 @@ def load_config(
 
     # Return the legacy concrete type (subclass) for compatibility.
     cfg = AppConfig.model_validate(model.model_dump())
-    from src.core.config.auto_append_first_prompt_hydration import (
-        hydrate_auto_append_first_prompt,
-    )
-
-    hydrate_auto_append_first_prompt(cfg)
     return cfg
 
 

src/core/config/auto_append_first_prompt_hydration.py

@@ -1,27 +1,29 @@
-"""Load first-user-message append suffix from configured file at startup."""
+"""Resolve first-user-message append suffix from configured file at startup."""
 
 from __future__ import annotations
 
 import logging
 from pathlib import Path
 from typing import TYPE_CHECKING
 
+from src.core.config.models.resolved_app_config import ResolvedAppConfig
+
 if TYPE_CHECKING:
     from src.core.config.app_config import AppConfig
 
 logger = logging.getLogger(__name__)
 
 
-def hydrate_auto_append_first_prompt(cfg: AppConfig) -> None:
-    """Read ``auto_append_first_prompt_filename`` into ``auto_append_first_prompt_text``.
+def resolve_auto_append_first_prompt_text(cfg: AppConfig) -> str | None:
+    """Resolve ``auto_append_first_prompt_filename`` into text content.
 
-    Clears ``auto_append_first_prompt_text`` when filename is unset. Raises
-    ``ValueError`` when a path is set but is not a readable regular file.
+    Returns ``None`` when filename is unset. Raises ``ValueError`` when a path is
+    set but is not a readable regular file.
     """
+
     raw = getattr(cfg, "auto_append_first_prompt_filename", None)
     if raw is None or not isinstance(raw, str) or not raw.strip():
-        cfg.auto_append_first_prompt_text = None
-        return
+        return None
 
     path = Path(raw.strip()).expanduser()
     resolved = path.resolve()
@@ -32,7 +34,6 @@ def hydrate_auto_append_first_prompt(cfg: AppConfig) -> None:
 
     text = path.read_text(encoding="utf-8")
     stripped = text.strip()
-    cfg.auto_append_first_prompt_text = stripped if stripped else None
 
     if stripped:
         if logger.isEnabledFor(logging.INFO):
@@ -41,9 +42,20 @@ def hydrate_auto_append_first_prompt(cfg: AppConfig) -> None:
                 len(stripped),
                 resolved,
             )
-    elif logger.isEnabledFor(logging.INFO):
+        return stripped
+
+    if logger.isEnabledFor(logging.INFO):
         logger.info(
             "Auto-append first prompt: file %s is empty or whitespace-only; "
             "nothing will be appended",
             resolved,
         )
+    return None
+
+
+def resolve_app_config(cfg: AppConfig) -> ResolvedAppConfig:
+    """Resolve startup-derived configuration values for runtime use."""
+
+    return ResolvedAppConfig(
+        auto_append_first_prompt_text=resolve_auto_append_first_prompt_text(cfg)
+    )

src/core/config/models/__init__.py

@@ -22,6 +22,7 @@
 )
 from src.core.config.models.non_forwardable_config import NonForwardableTaggingConfig
 from src.core.config.models.notification import NotificationConfig
+from src.core.config.models.resolved_app_config import ResolvedAppConfig
 from src.core.config.models.rewriting import (
     EditPrecisionConfig,
     ModelAliasRule,
@@ -57,6 +58,7 @@
     "PlanningPhaseConfig",
     "CanonicalRequestProcessingConfig",
     "ReasoningModelTokenFloorConfig",
+    "ResolvedAppConfig",
     "RewritingConfig",
     "ResilienceConfig",
     "RoutingConfig",

src/core/config/models/app_config_model.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import logging
+import warnings
 from pathlib import Path
 from typing import Any
 
@@ -195,5 +196,17 @@ def get(self, key: str, default: Any = None) -> Any:
             return default
 
     def set(self, key: str, value: Any) -> None:
-        """Set a configuration value (legacy convenience)."""
+        """Set a configuration value (legacy convenience).
+
+        .. deprecated::
+            ``IConfig.set()`` is deprecated.  Use ``model_copy(update=...)`` on
+            the immutable model or mutate runtime state via ``ApplicationState``
+            instead.
+        """
+        warnings.warn(
+            "IConfig.set() is deprecated; use model_copy(update=...) or mutate "
+            "runtime state via ApplicationState instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         setattr(self, key, value)

src/core/config/models/resolved_app_config.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from pydantic import ConfigDict
+
+from src.core.interfaces.model_bases import DomainModel
+
+
+class ResolvedAppConfig(DomainModel):
+    """Startup-resolved configuration values derived from AppConfig."""
+
+    model_config = ConfigDict(frozen=True)
+
+    auto_append_first_prompt_text: str | None = None

src/core/persistence.py

@@ -541,22 +541,37 @@ def _parse_and_validate_failover_element(
         return f"{backend_name}:{model_name}", None
 
     def _prune_unavailable_routes(self) -> None:
+        """Compute effective failover routes and store in runtime state.
+
+        This method no longer mutates ``app_config.failover_routes``.  Instead
+        it computes the subset of declared routes whose elements are all
+        functional and stores them as effective routes in the application
+        state service.
+        """
         if not self.app_state or not self.app_state.app_config:
             return
 
-        self.app_state.app_config.failover_routes = {
-            name: route
-            for name, route in self.app_state.app_config.failover_routes.items()
-            if (
-                getattr(route, "elements", None) if hasattr(route, "elements") else route.get("elements")  # type: ignore[attr-defined]
+        declared_routes = self.app_state.app_config.failover_routes
+        for name, route in declared_routes.items():
+            elements = (
+                getattr(route, "elements", [])
+                if hasattr(route, "elements")
+                else route.get("elements", [])  # type: ignore[attr-defined]
             )
-            and all(
+            if not elements:
+                continue
+            if not all(
                 self.app_state.app_config.model_is_functional(element)
-                for element in (
-                    getattr(route, "elements", []) if hasattr(route, "elements") else route.get("elements", [])  # type: ignore[attr-defined]
-                )
+                for element in elements
+            ):
+                continue
+            self.app_state.set_failover_route(
+                name,
+                {
+                    "policy": getattr(route, "policy", "k"),
+                    "elements": list(elements),
+                },
             )
-        }
 
     def _apply_failover_routes(self, froutes_value: Any) -> list[str]:
         warnings: list[str] = []

src/core/services/request_transform_pipeline.py

@@ -288,10 +288,10 @@ async def _apply_auto_append_first_user_suffix(
         ) and context.extensions.get("auxiliary_request"):
             return request
 
-        app_config = self._get_app_config()
+        resolved_app_config = self._get_resolved_app_config()
         suffix_raw = (
-            getattr(app_config, "auto_append_first_prompt_text", None)
-            if app_config is not None
+            getattr(resolved_app_config, "auto_append_first_prompt_text", None)
+            if resolved_app_config is not None
             else None
         )
         suffix = str(suffix_raw).strip() if suffix_raw is not None else ""
@@ -455,6 +455,31 @@ def _get_app_config(self) -> Any | None:
         except (AttributeError, KeyError, TypeError):
             return None
 
+    def _get_resolved_app_config(self) -> Any | None:
+        if self._app_state is None:
+            return None
+
+        try:
+            resolved = self._app_state.get_setting("resolved_app_config")
+        except (AttributeError, KeyError, TypeError):
+            resolved = None
+
+        if resolved is not None:
+            return resolved
+
+        app_config = self._get_app_config()
+        if app_config is None:
+            return None
+
+        try:
+            from src.core.config.auto_append_first_prompt_hydration import (
+                resolve_app_config,
+            )
+
+            return resolve_app_config(app_config)
+        except Exception:
+            return None
+
     def _get_session_state(self, session: object) -> Any | None:
         try:
             return getattr(session, "state", None)