# Visual Flow architecture

Flow is an authoring/orchestration layer. It does not replace the thermostat, schedule, group or device engines.

## Compilation

- `weekday + time_range -> zone_thermostat` with schedule-compatible settings compiles to a native `Schedule`.
- Richer DAGs compile to native `Automation` rows with `trigger_kind = "flow"`.
- Generated rows keep `flow_id` and `flow_node_id` and are read-only in the legacy editors.
- The Flow source graph plus all of its generated schedule/automation rows are replaced in one SQLite transaction.
- Flow updates require `expected_revision`; stale editor tabs receive HTTP 409.

## Existing control domains remain authoritative

- `zone_thermostat` writes the existing persistent Zone intent and wakes the normal thermostat cycle.
- `group_action` calls the existing `control_group` path, including custom group targets.
- `device_action` uses the existing `DeviceCommand` / automatic-device path.
- Thermostat hysteresis, compressor protection, schedule hand-back, manual/local ownership and Temporary Quick Thermostat keep their existing priority.
- GREE fan/quiet/sleep and dry/fan HVAC modes are suppressed on thermostat-assigned devices when they would fight the regulator. Device-only features such as light/turbo/swing/air/xfan/health remain available through the normal command path.

## Concurrency invariants

Structural Flow writes use the global order:

`configuration -> automation -> schedule -> thermostat-cycle`

Thermostat/device actions then use:

`automation -> schedule -> thermostat-cycle -> zone -> device`

Group actions use the existing group order:

`automation -> house -> thermostat-cycle -> group -> zone(s) -> device`

The control loop runs thermostat arbitration and automation arbitration sequentially. Automation execution reloads the row after acquiring the automation lock and skips it when `updated_at` changed. Same-cycle due automations deterministically claim target devices so two rules cannot issue conflicting commands to the same unit in one pass. Polling and physical commands share per-zone/per-device locks.

Holding the automation lock across the physical action is deliberate: Flow cannot be deleted/recompiled while an already-selected action is in flight. Do not shorten this ownership window without adding an explicit execution-generation/token mechanism.

External sensor values can naturally change between condition sampling and action execution. This is normal sampled-control semantics, not a persistent-state race; safety/ownership is rechecked at the action boundary.

## Home Assistant safety

`ha_state`, `ha_numeric`, `ha_attribute` and `ha_available` fail closed. Connection failures, missing attributes and non-numeric numeric states evaluate to `false` and appear as an error object in dry-run traces. This prevents `NOT` / `neq` branches from becoming true merely because Home Assistant is unavailable.

## Diagnostics

The Flow editor exposes:

- dry-run at an arbitrary date/time,
- per-source overrides,
- per-node trace,
- `would_execute` and ownership/block reason,
- Flow-scoped execution/dry-run logs,
- import/export of versioned `.flow.json` source graphs.

Dry-run never mutates thermostats, devices, groups, schedules or automations.

## Blocks

Condition/source blocks currently include weekday, time range, date range, application Night mode, outdoor/device/zone temperature, house mode, device state, thermostat/zone state, group state, Home Assistant state/numeric/attribute/availability and a diagnostic constant. Logic blocks are AND, OR and NOT.

Actions include thermostat zone, GREE device and climate group. Direct GREE actions expose power, HVAC mode, target temperature, fan speed, vertical/horizontal swing, quiet, turbo, light, air, xfan, health and sleep.

## Built-in templates

The editor ships editable templates for:

- workday comfort,
- weather-aware comfort,
- smart AND/OR demand,
- device resilience,
- night group control,
- Home Assistant window guard,
- presence comfort/eco,
- frost protection,
- nested OR + NOT guard,
- application Night-mode quiet profile.

## Good next stateful blocks

The next useful additions should be implemented with persisted runtime state rather than pretending they are stateless predicates:

- `for X minutes` / stable-for,
- debounce,
- hysteresis block,
- rising/falling edge,
- cooldown/rate limit independent of the action,
- delay/timer,
- retry/backoff,
- variables/counters,
- reusable subflows/macros,
- explicit priority/mutex groups for actions,
- trace replay from historical sensor samples.

These need durable state and restart semantics before they should be exposed in the editor.