# Configuration Management

## Requirements

### Requirement: Extensible Configuration Acquisition

The system SHALL provide an `AcquirerAbc` protocol that enables pluggable
configuration sources with a default TOML implementation.

#### Scenario: Default TOML configuration loading
- **WHEN** no custom acquirer is provided to `prepare()`
- **THEN** the `TomlAcquirer` loads configuration from TOML files
- **AND** configuration is merged into an accretive dictionary

#### Scenario: Custom configuration acquirer
- **WHEN** an application provides a custom `AcquirerAbc` implementation
- **THEN** the custom acquirer is used for configuration loading
- **AND** the result is merged into the standard configuration dictionary

#### Scenario: Configuration source protocol compliance
- **WHEN** a custom acquirer implements `AcquirerAbc`
- **THEN** it must provide a method that returns a configuration dictionary
- **AND** the dictionary is merged with environment overrides and edits

### Requirement: Hierarchical Configuration Merging

The system SHALL support hierarchical configuration loading with include
processing, template variables, and environment overrides.

#### Scenario: Configuration file includes
- **WHEN** a TOML file contains an `includes` array of file paths
- **THEN** referenced files are loaded and merged in order
- **AND** later files override values from earlier files

#### Scenario: Template variable expansion
- **WHEN** configuration values contain `{variable}` placeholders
- **THEN** placeholders are expanded using values from the configuration itself
- **AND** undefined variables cause a clear error

#### Scenario: Environment variable overrides
- **WHEN** environment variables match the pattern `{APP}_CONFIG_{KEY}`
- **THEN** those values override configuration file values
- **AND** environment overrides take highest precedence

### Requirement: Configuration Edits

The system SHALL support configuration edits that are applied after loading
and before final state assembly.

#### Scenario: Edit application during initialization
- **WHEN** `configedits` are provided to `prepare()`
- **THEN** edits are applied to the loaded configuration in order
- **AND** the final configuration reflects all edits

#### Scenario: Edit types
- **WHEN** configuration edits include set, update, and delete operations
- **THEN** set replaces a value, update merges, and delete removes
- **AND** edits operate on the nested dictionary path

### Requirement: Enablement Tristate

The system SHALL provide an `EnablementTristate` enum for disable/retain/enable
configuration options.

#### Scenario: Boolean conversion
- **WHEN** `EnablementTristate.Disable` is evaluated in a boolean context
- **THEN** it returns `False`
- **AND** `EnablementTristate.Enable` returns `True`

#### Scenario: Retain natural state
- **WHEN** `EnablementTristate.Retain` is used
- **THEN** the system preserves the existing or default behavior
- **AND** no explicit enable/disable override is applied