manual_slop/conductor/code_styleguides/config_state_owner.md

Config I/O State Ownership

Rule: The AppController is the single source of truth for the in-memory config (self.config) and the only authorized caller of the file I/O primitives in src/models.py.

Why

1. The controller owns the in-memory state. If other modules write to config.toml directly, the controller's self.config silently drifts from disk. Tests can corrupt the user's TOML files; users lose data without warning.
2. Test isolation breaks. When models.save_config(...) is called from anywhere in src/, tests cannot intercept the write without patching the I/O primitive. The test then couples to the file format, not the controller's behavior.
3. Path resolution can't be enforced. The controller respects SLOP_CONFIG env var at call time. Direct calls to models.save_config would only respect it if the path is re-resolved (which it is in _save_config_to_disk, but only because someone remembered).

What is Forbidden in src/

• models.load_config(...) (legacy public function)
• models.save_config(...) (legacy public function)
• models._load_config_from_disk(...) (private I/O primitive)
• models._save_config_to_disk(...) (private I/O primitive)

The only allowed call sites are inside AppController itself (load_config() and save_config() methods).

The Public API

# In AppController:
def load_config(self) -> Dict[str, Any]:
    """Re-read the global config.toml from disk and update self.config."""
    self.config = models._load_config_from_disk()
    return self.config

def save_config(self) -> None:
    """Flush self.config to disk."""
    models._save_config_to_disk(self.config)

Callers (including gui_2.py, commands.py, etc.) go through the controller:

# In App class methods (gui_2.py): __getattr__ delegates to controller
self.save_config()      # -> controller.save_config()
app.save_config()       # -> controller.save_config() (via __getattr__)
app.load_config()       # -> controller.load_config() (via __getattr__)

# In AppController:
self.save_config()      # direct
self.load_config()      # direct

Test Patterns

Tests should mock the controller methods, not the I/O primitives:

# CORRECT: route through the controller
with patch('src.app_controller.AppController.load_config',
           return_value={'ai': {...}, 'projects': {...}}):
    app = App()  # controller's load_config returns the mock

with patch('src.app_controller.AppController.save_config'):
    app._save_paths()  # controller's save_config is a no-op
    app.save_config.assert_called_once()  # verify the call

# WRONG: patch the I/O primitive
with patch('src.models._save_config_to_disk'):  # bypasses the controller
    app._save_paths()  # still hits the I/O primitive if production bypasses

The mock_app and app_instance fixtures in tests/conftest.py follow the correct pattern: they patch AppController.load_config and AppController.save_config to prevent real I/O and to provide a default config.

Exceptions

The only allowed non-controller call site is the test_models_no_top_level_tomli_w.py test, which specifically verifies the lazy-load behavior of the I/O primitive itself (tomli_w import timing). This test is exempt from the audit.

Enforcement

The scripts/audit_no_models_config_io.py script enforces this rule.

• python scripts/audit_no_models_config_io.py — human report
• python scripts/audit_no_models_config_io.py --strict — exit 1 on violation
• python scripts/audit_no_models_config_io.py --json — machine output

CI should run the --strict mode on every PR.

See Also

• docs/guide_app_controller.md — the AppController's role
• docs/guide_models.md — the models module
• conductor/product.md — "Modular Controller Pattern" principle