# Code audit — 0.12.0

Scope: settings/configuration API, frontend consumers, configuration import/export, and the largest control handlers touched by the API/runtime ownership changes.

## Breaking API redesign

0.12.0 intentionally removes the previous monolithic/compatibility routes. There are no aliases.

| Removed | Replacement |
| --- | --- |
| `GET/PUT /api/settings` | functional `/api/settings/*` resources |
| `GET/PUT /api/debug` | `GET/PUT /api/settings/debug` |
| `PUT /api/events/retention` | `GET/PUT /api/settings/history` |
| `GET /api/settings/export` | `GET /api/configuration/export` |
| `POST /api/settings/import` | `POST /api/configuration/import` |

Functional settings resources:

- `/api/settings/application`
- `/api/settings/gree`
- `/api/settings/history`
- `/api/settings/influxdb`
- `/api/settings/notifications`
- `/api/settings/night`
- `/api/settings/home-assistant`
- `/api/settings/debug`

The bootstrap payload no longer exposes runtime settings. The Web UI fetches each settings resource explicitly.

## Correctness and security findings addressed

- Settings writes no longer require a full `RuntimeSettings` document, so changing one section cannot overwrite unrelated settings.
- Integration secrets are never returned by settings GET endpoints. Secret-bearing PUT fields are optional: omitted/null preserves the stored value; an explicit empty string clears it.
- Configuration backup/restore was separated from runtime settings into `/api/configuration/*`.
- Configuration format was raised to version `3`; imports accept only version `3`.
- Format-v3 imports reject unsupported control strategies; `0.12.0` accepts only `setpoint`.
- Import validates and normalizes the same GREE/history/InfluxDB/notification/night/Home Assistant constraints used by functional settings endpoints.
- Shared Flow inputs in an imported backup are validated against devices/zones/groups from that backup, not against the configuration currently stored in the database.
- Obsolete `house_power_enabled` and `master_power_enabled` compatibility state was removed from runtime/settings/group responses.
- Settings WebSocket broadcasts are section-specific (`settings.<section>.updated`) instead of the former whole-settings event.

## Refactoring performed

Approximate function lengths are shown to make the audit measurable; line count is only a hotspot signal, not a quality metric by itself.

| Area | Before | After |
| --- | ---: | ---: |
| `engine::control_group` | 292 | 137 |
| `api::apply_zone_control_patch` | 415 | 214 |
| `engine::control_zones` | 666 | 413 |
| monolithic `api::update_settings` | 83 | removed |
| monolithic configuration validator | 155 | removed/split |
| monolithic settings import handler | 98 | removed/split |

New smaller responsibilities include:

- GREE settings normalization and compressor-runtime cleanup;
- InfluxDB and notification update/secret merge helpers;
- Home Assistant alias/entity/input validation;
- configuration header, IDs, flows, schedules and automation validation;
- configuration runtime sanitation, resource locking, detached-device shutdown and reconciliation;
- group patch validation, climate changes, power changes and ownership updates;
- Temporary Quick Thermostat start, target and finish resolution;
- control-cycle outdoor sensor resolution, parallel room sensor reads, temperature-source selection and pre-control state handling.

## Remaining hotspots

`control_zones` remains the largest function because it is the ordered thermostat-cycle orchestrator and contains compressor/setpoint command planning. It was reduced substantially without changing lock ordering or splitting the core state machine across opaque abstractions. Flow evaluation/compiler functions remain domain-heavy but were not changed as part of this API release because they are independent of the settings redesign and already have dedicated logical verification.

## Frontend/documentation

- Web UI settings loading/saving uses only the new functional endpoints.
- Configuration import/export uses `/api/configuration/*`.
- Realtime settings handling uses section-specific events and serializes WebSocket message processing so reconnect bootstrap cannot race later updates.
- `docs/API.md`, `docs/openapi.json`, README and smoke/static Flow checks were updated for 0.12.0.