-
Notifications
You must be signed in to change notification settings - Fork 4
Description
Context
Stemming from #429.
SonataConfig currently loads Sonata configuration entities (e.g. ConnectionOverride, Conditions, …) and converts them into plain dicts. These dicts are then mutated throughout the codebase:
- keys are added for local or transient state
- keys are removed to encode semantic meaning (e.g. “invalid”, “disabled”)
- values are overridden via CLI
This pattern is widespread.
Problem
Using dicts as configuration objects causes structural issues:
- No schema enforcement: keys can be added, removed, or misspelled silently
- Configuration and runtime state are mixed
- Semantics are implicit (presence/absence of keys)
- Hard to reason about when a configuration is complete or valid
- CLI overrides can introduce inconsistent states
Configuration is treated as a mutable bag of data rather than a domain object.
Scope of this epic
This epic is intentionally limited in scope.
Goal:
Replace dict-based internal configuration handling with explicit, typed configuration objects so that:
- configuration structure is explicit
- keys cannot be arbitrarily added or removed
- semantics are expressed via fields, not conventions
Immutability, freezing, and lifecycle enforcement are explicitly out of scope and may be addressed later.
Proposal
-
Introduce proper internal config objects
For each Sonata configuration concept currently represented as a dict, introduce a corresponding internal config object (if mutability is needed otherwise rely on the original sonata config object) with explicit, typed fields. Dicts are no longer used as the primary internal representation. -
One-way conversion from SonataConfig
SonataConfig remains the external, immutable source of truth. At load time, Sonata objects are converted once into internal config objects. Internal code never mutates raw dicts. -
Controlled mutation during setup
Internal config objects may be mutated during setup (CLI overrides, defaults, normalization), but only via explicit attribute access. Adding or removing keys is no longer possible. -
Separation of concerns
Configuration objects represent configuration only. Runtime or execution state must not be encoded by mutating config objects.
Non-goals
Out of scope for this epic:
- enforcing immutability or freeze semantics
- deep validation or invariant checking
- multiple config layers (parsed vs resolved)
- runtime enforcement of mutation phases
Why this matters
Even without immutability, this change:
- removes an entire class of bugs (dynamic keys)
- makes configuration structure explicit and reviewable
- improves readability and maintainability
- enables future improvements without rework
This is a necessary first step.
Acceptance criteria
- No internal code path relies on mutating configuration dicts
- All Sonata-derived configuration is represented by explicit config objects
- No configuration semantics are encoded via key presence/absence
- CLI overrides operate on config object fields, not dict keys