@enyo-energy/energy-app-sdk 1.29.0 → 1.31.0

package/README.md

@@ -3110,13 +3110,76 @@ class MyHeatpumpApp extends HeatpumpIntegrationEnergyApp {
 
 Drives a heatpump. Manages building / DHW overheating commands and grid-power-availability announcements.
 
-- **Subscribed commands:** `HeatpumpOverheatingV1`, `HeatpumpAvailablePowerAnnouncementV1`, `SetHeatpumpAvailablePowerV2`, `SetHeatpumpRoomTemperatureV1`, `GridOperatorPowerLimitationV1` (broadcast)
+> **Preferred: control heatpumps with the V3 messages.** `HeatpumpControlV3` (power, power sources, which zones to heat now, until when), `HeatpumpControlCancelV3` (cancel a session) and `HeatpumpControlStatusV3` (progress) are the preferred way to control a heatpump — for energy managers sending commands and for integrations receiving them. Use them for all new work. `HeatpumpOverheatingV1`, `SetHeatpumpAvailablePowerV2` and `HeatpumpAvailablePowerAnnouncementV1` are deprecated and only remain for heatpumps that do not declare `ControlV3`. See [HeatpumpControlV3](#heatpumpcontrolv3). Likewise, a heatpump offers its flexibility with `HeatpumpFlexibilityAnnouncementV3` rather than the generic `ApplianceFlexibilityAnnouncementV1` / `V2` — see [HeatpumpFlexibilityAnnouncementV3](#heatpumpflexibilityannouncementv3).
+
+- **Subscribed commands:** `HeatpumpControlV3`, `HeatpumpControlCancelV3`, `HeatpumpOverheatingV1` (deprecated), `HeatpumpAvailablePowerAnnouncementV1` (deprecated), `SetHeatpumpAvailablePowerV2` (deprecated), `SetHeatpumpRoomTemperatureV1`, `GridOperatorPowerLimitationV1` (broadcast)
 - **Implement:** `handleHeatpumpOverheating`, `handleHeatpumpAvailablePowerAnnouncement`, `handleSetHeatpumpAvailablePower`, `handleGridOperatorPowerLimitation`
-- **Optional override:** `handleSetHeatpumpRoomTemperature` — write a measured room temperature into a heating circuit. Answers `NotSupported` by default; override it when the heatpump declares `RoomTemperatureInput`.
+- **Optional overrides:**
+  - `handleSetHeatpumpRoomTemperature` — write a measured room temperature into a heating circuit. Answers `NotSupported` by default; override it when the heatpump declares `RoomTemperatureInput`.
+  - `handleHeatpumpControl` — support `HeatpumpControlV3` (see below). Answers `NotSupported` by default; override it and declare `ControlV3`.
+  - `handleHeatpumpControlCancel` — withdraw a cancelled session on the device. By default `Accepted` for heatpumps declaring `ControlV3`, `NotSupported` otherwise.
+  - `onHeatpumpControlEnded(applianceId, cause)` — return the heatpump to its own behaviour when a session ends; `cause` is `HeatpumpControlEndCauseEnum.Expired`, `Ended` or `Cancelled`. Does nothing by default.
+  - `resolveHeatpumpMetadata(applianceId)` — the metadata actions are validated against. Defaults to the stored appliance's `heatpump` metadata.
+- **Helpers for a V3 implementation:** `checkHeatpumpControlActions(message)` (validates every action against metadata and offer), `isHeatpumpControlChanged(message)` (new session or changed actions?), and the exported `computeHeatpumpSetpointRaise(...)` and `combineHeatpumpControlAnswers(...)`.
 - **Publish helpers:**
+  - `publishHeatpumpControlStatus(applianceId, {sessionId, actions})` — how a session's actions progress (`HeatpumpControlStatusV3`).
+  - `publishHeatpumpFlexibility(applianceId, options, {validForSeconds?, repeatEverySeconds?})` — offer per zone how far the heatpump can be raised right now (`HeatpumpFlexibilityAnnouncementV3`); repeated automatically until replaced (see below).
   - `publishHeatpumpValuesUpdate(applianceId, values)` — operation mode, electrical and thermal power, energies.
   - `publishHeatpumpTemperatures(applianceId, temperatures)` — outdoor, flow / target flow / return, DHW tanks, heating circuits (room, flow, target flow, return), buffer tank.
 
+#### HeatpumpControlV3
+
+**The preferred way to control a heatpump.** Energy managers send `HeatpumpControlV3` / `HeatpumpControlCancelV3` to heatpumps declaring `ControlV3`, and the deprecated `HeatpumpOverheatingV1` / `SetHeatpumpAvailablePowerV2` to all others — the choice comes from the metadata, not from probing. Integrations override `handleHeatpumpControl`, declare `ControlV3` (and `PvSurplusSignal` where the device takes a PV surplus signal), and report progress with `publishHeatpumpControlStatus`.
+
+One message per control session says **how much** power (`availablePowerW`), **from where** (`powerSources`: PV / battery / grid), **which zones to heat now** (`actions`: DHW, buffer tank or room, each with `index`, `deltaK` and an optional `heatSource`) and **until when** (`validUntilIso`).
+
+```typescript
+{
+    sessionId: 'night-tariff-2026-10-15',          // the same across every repeat
+    validUntilIso: '2026-10-15T00:01:00.000Z',     // liveness: repeated ~every 10 s, ~60 s ahead
+    availablePowerW: 3000,
+    powerSources: [{ source: EnyoPowerSourceEnum.Grid, powerW: 3000 }],
+    actions: [{ target: EnyoHeatpumpControlTargetEnum.Dhw, index: 0, deltaK: 5 }],
+}
+```
+
+- **An action means "heat this zone now".** It pulls heating into a cheap or sunny period — e.g. night tariff 0–5 h. Answer it `Accepted` only when the device will actually start heating. A setpoint-only heatpump (Stiebel Eltron, Nibe) only starts once the temperature is a hysteresis below the setpoint, so write at least `currentTemperature + hysteresisK` (`domesticHotWater[].hysteresisK` / `bufferTanks[].hysteresisK`) even if `deltaK` asks for less. If `maxTemperatureC` leaves no such setpoint, answer `Rejected` — never `Accepted` with nothing happening. `computeHeatpumpSetpointRaise({setpointC, deltaK, currentTemperatureC, hysteresisK, maxTemperatureC})` does the arithmetic the same way for every app.
+- **Room `deltaK` is always Kelvin of room temperature.** On an outdoor-controlled circuit (`heatingControlReference: Outdoor`) the app translates it into a heating-curve shift, on a room-controlled one into a higher room setpoint. The energy manager never sends a curve shift. Above the circuit's `heatingCutoffOutdoorTemperatureC` a room action cannot take effect and is `Rejected`.
+- **Report what was written.** Each `actionResults` entry carries `appliedTargetTemperatureC` (the setpoint written), `appliedDeltaK` (the effective raise, possibly above `deltaK`) and, for a room on an outdoor-controlled circuit, `appliedHeatingCurveShiftK`.
+- **Sessions.** Repeats arrive about every 10 s with the same `sessionId`; apply the actions only when `isHeatpumpControlChanged(message)` says the session or its actions changed, and just update the power otherwise. The base class handles liveness for every V3 implementation: it rejects a message whose `validUntilIso` is invalid or past, and calls `onHeatpumpControlEnded` when no repeat arrives by `validUntilIso` (`Expired`), on a message with no actions and no `availablePowerW` (`Ended` — passed to `handleHeatpumpControl` first, so the device can be reset at once), or on a cancel (`Cancelled`).
+- **Cancelling.** `HeatpumpControlCancelV3` with a `sessionId` cancels that session right away, instead of waiting up to ~60 s for `validUntilIso` to lapse. It only touches the named session, so a newer one that replaced it is safe, which an empty `HeatpumpControlV3` cannot guarantee. Idempotent: `Accepted` also when the session is no longer running. Stop repeating the session first, or the next repeat starts it again.
+- **Answers per action.** The acknowledgment carries one `actionResults` entry per action; return them in `IntegrationCommandResponse.actionResults` and the base class passes them through. The top-level `answer` is `Accepted` as soon as the power or one action is accepted, `NotSupported` only when nothing is supported, otherwise `Rejected` (`combineHeatpumpControlAnswers`).
+- **Progress.** `HeatpumpControlStatusV3` reports each action as `Waiting` (accepted, not heating yet — defrost, minimum off-time), `Running`, `Completed` (target reached — the energy manager may end the session early) or `Aborted` (stopped or refused — the energy manager re-plans), with `currentTemperatureC`, `appliedTargetTemperatureC`, `startedAtIso`, `endedAtIso` and a `reason`. Send it on every state change and once more when the session ends.
+- **Validation** (`checkHeatpumpControlActions(message)`, or `validateHeatpumpControlAction(action, metadata, powerSources, offer?)` directly):
+  - A heating rod (`heatSource` `HeatingRod` / `Both`) runs on PV surplus only: rejected unless `powerSources` are PV alone, and `NotSupported` without `HeatingRodControllable`.
+  - Each target needs its overheating feature (`DomesticHotWaterOverheating`, `BufferTankOverheating`, `RoomOverheating`), else `NotSupported`.
+  - DHW must stay within `domesticHotWater[].maxTemperatureC`: setpoint + `deltaK` above it is rejected.
+  - When the session names an `offerId`, each action must fit the heatpump's current offer.
+
+#### HeatpumpFlexibilityAnnouncementV3
+
+The heatpump's offer, in the vocabulary of `HeatpumpControlV3`: per zone (`target` + `index`), how far it can be raised right now (`maxDeltaK` above `setpointC`, room in Kelvin of room temperature) and the smallest raise that actually starts it (`minDeltaK`, e.g. the remaining hysteresis), with which heat source at what power (`heatSources`: compressor and heating rod as separate entries, each with a `power` band and an optional `estimatedElectricalKwh` for the full raise), and when (`earliestStartIso` / `latestStartIso`, `minDurationMinutes`). An optional `required: {deltaK, byIso}` turns a "may" into a "must, by then" — e.g. hot water dropping below comfort at 18:00. Declare `FlexibilityAnnouncementV3` on the heatpump; for such heatpumps it supersedes the generic `ApplianceFlexibilityAnnouncementV1` / `V2`.
+
+```typescript
+const offerId = await this.publishHeatpumpFlexibility('heatpump-1', [{
+    target: EnyoHeatpumpControlTargetEnum.Dhw,
+    index: 0,
+    currentTemperatureC: 47,
+    setpointC: 50,
+    maxDeltaK: 10,
+    heatSources: [
+        { heatSource: EnyoHeatpumpHeatSourceEnum.Compressor, power: { minWatt: 800, maxWatt: 2300, stepWatt: 100 }, estimatedElectricalKwh: 1.4 },
+        { heatSource: EnyoHeatpumpHeatSourceEnum.HeatingRod, power: { minWatt: 3000, maxWatt: 3000, stepWatt: 3000 }, estimatedElectricalKwh: 4.1 },
+    ],
+    required: { deltaK: 3, byIso: '2026-10-14T18:00:00.000Z' },
+}]);
+```
+
+- **Lifecycle.** The latest offer per appliance replaces the previous one and holds until `validUntilIso`. `publishHeatpumpFlexibility` repeats it with a fresh `validUntilIso` (default: valid 15 min, repeated every 5 min) until you call it again, and stops repeating on `stop()`. Publish `[]` to withdraw the offer.
+- **`offerId`** is derived from what is offered (`heatpumpFlexibilityOfferId`), ignoring measured values and order — it stays the same while the tank warms up and changes when the offer changes.
+- **Answering an offer.** The energy manager answers with `HeatpumpControlV3` — one action per offered zone, `deltaK` ≤ `maxDeltaK`, a `heatSource` from the offered ones — and names the offer in `data.offerId`. When a session names an `offerId`, the base class checks every action against the heatpump's current offer and rejects what was not offered. A session without `offerId` is the energy manager's own plan and is checked against the metadata only.
+- **Validation** (`validateHeatpumpFlexibilityAnnouncement(data, metadata?)`, run by `publishHeatpumpFlexibility` before sending): `maxDeltaK` positive; at least one heat source, none twice, a sane power band; start window and `required.byIso` valid, `required.deltaK` ≤ `maxDeltaK`; each zone at most once; and against the metadata, DHW `setpointC + maxDeltaK` ≤ `maxTemperatureC`, a heating rod only with `HeatingRodControllable`, and each target's overheating feature declared.
+
 #### Advanced heatpump metadata
 
 Beyond tanks and circuits, the heatpump metadata (`EnyoHeatpumpApplianceMetadata`) can carry what the device is configured to do. Declare each part with its feature flag in `availableFeatures` so consumers know to expect it:
@@ -3127,6 +3190,11 @@ Beyond tanks and circuits, the heatpump metadata (`EnyoHeatpumpApplianceMetadata
 | `TimeProgram` | `heatingCircuits[].timeProgram` and `domesticHotWater[].timeProgram` — weekly periods (`daysOfWeek` 0 = Sunday, local `HH:mm` times, may wrap past midnight) switching between `Comfort` / `Reduced` / `Off` / `Boost` |
 | `RoomTemperature` | `heatingCircuits[].roomTemperatureC` in `HeatpumpTemperaturesUpdateV1`; where it is measured goes in `heatingCircuits[].roomTemperatureSource` (`None` / `Internal` / `External`) and, for an enyo sensor, `roomTemperatureSensor` |
 | `RoomTemperatureInput` | The heatpump accepts measured room temperatures via `SetHeatpumpRoomTemperatureV1` |
+| `PvSurplusSignal` | The heatpump takes `availablePowerW` of `HeatpumpControlV3` as a PV surplus signal (e.g. Lambda register 102). Supersedes the deprecated `AvailablePowerAnnouncement` |
+| `ControlV3` | The heatpump's app handles `HeatpumpControlV3` / `HeatpumpControlCancelV3` and reports `HeatpumpControlStatusV3`. The energy manager sends V3 only to heatpumps declaring it. Needs at least one overheating feature to be actionable |
+| `FlexibilityAnnouncementV3` | The heatpump publishes `HeatpumpFlexibilityAnnouncementV3` offers; the energy manager plans from them instead of deriving the headroom from metadata. Needs at least one overheating feature to be actionable |
+| — | `heatingCircuits[].heatingControlReference` — what the circuit steers by: `Outdoor` (heating curve) or `Room`. Independent of `roomTemperatureSource`, which says where the room is measured |
+| — | `heatingCircuits[].heatingCutoffOutdoorTemperatureC` — the heatpump's own heating cut-off (Heizgrenze / Sommerabschaltung) setting. Above it a room action cannot take effect. Unlike the learned `building.heatingLimitC`; the validator warns when the two differ by more than 3 K |
 | `FlowTemperature` / `ReturnTemperature` | `heatpumpFlowTemperatureC`, `heatpumpTargetFlowTemperatureC`, `heatpumpReturnTemperatureC` and per-circuit `flowTemperatureC`, `targetFlowTemperatureC`, `returnTemperatureC` in `HeatpumpTemperaturesUpdateV1` |
 
 `updateAppliance` replaces the whole `heatingCircuits` / `domesticHotWater` array, so use the `ApplianceManager` helpers to change a single entry:
@@ -3522,33 +3590,58 @@ Both are for marking on the same power scale a consumer already draws from `maxC
 
 ### BatteryCommandForecast
 
-Relative `{seconds, mode, powerW}` schedule where `mode` is one of `'charge'`, `'discharge'`, or `'auto'`. `auto` returns control to the appliance and must always carry `powerW = 0`.
+A discriminated union on `mode`:
+
+- `mode: 'auto'` — hand the battery back to its own logic over the horizon; no schedule. May carry an optional `reason` (`EnyoDataBusCommandReason`) saying **why** nothing is prescribed — e.g. `PriceSpreadTooSmall` when trading would not pay. Set it only when every Auto slot of the horizon shares the same reason; when they differ, leave it out rather than guess. Without it, an empty Auto forecast tends to read as "no forecast".
+- `mode: 'schedule'` — follow `relativeSchedule`, a list of `{seconds, direction, powerW}` setpoints, where `direction` is `charge`, `discharge` or `idle`.
 
 The type is named `BatteryCommandForecast` to make the distinction with the existing [`BatteryForecast`](#batteryforecast) class (which forecasts state-of-charge from history) explicit.
 
 ```typescript
 import {
+    ApplianceForecastResolutionEnum,
     BatteryCommandForecast,
+    BatteryCommandForecastDirectionEnum,
     BatteryCommandForecastModeEnum,
+    EnyoCurrencyEnum,
+    EnyoDataBusCommandReasonCategoryEnum,
+    EnyoDataBusCommandReasonTypeEnum,
 } from '@enyo-energy/energy-app-sdk';
 
-const forecast: BatteryCommandForecast = {
+// A planned cadence:
+const scheduled: BatteryCommandForecast = {
+    resolution: ApplianceForecastResolutionEnum.FifteenMinutes,
+    mode: BatteryCommandForecastModeEnum.Schedule,
     relativeSchedule: [
-        { seconds: 0,    mode: BatteryCommandForecastModeEnum.Charge,    powerW: 3000 },
-        { seconds: 1800, mode: BatteryCommandForecastModeEnum.Discharge, powerW: 2500 },
-        { seconds: 3600, mode: BatteryCommandForecastModeEnum.Auto,      powerW: 0    },
+        { seconds: 0,    direction: BatteryCommandForecastDirectionEnum.Charge,    powerW: 3000 },
+        { seconds: 1800, direction: BatteryCommandForecastDirectionEnum.Discharge, powerW: 2500 },
+        { seconds: 3600, direction: BatteryCommandForecastDirectionEnum.Idle,      powerW: 0    },
     ],
     estimatedSavings: { costSavings: 0.18, currency: 'EUR' },
 };
+await forecasts.publishBatteryForecast('battery-1', scheduled);
 
-await forecasts.publishBatteryForecast('battery-1', forecast);
+// Nothing planned, and why:
+const auto: BatteryCommandForecast = {
+    resolution: ApplianceForecastResolutionEnum.FifteenMinutes,
+    mode: BatteryCommandForecastModeEnum.Auto,
+    reason: {
+        type: EnyoDataBusCommandReasonTypeEnum.PriceSpreadTooSmall,
+        category: EnyoDataBusCommandReasonCategoryEnum.EnergyPrice,
+        electricityPricePerKwh: 0.352,
+        currency: EnyoCurrencyEnum.EUR,
+        context: { arbitrage: { buyPricePerKwh: 0.352, breakEvenPricePerKwh: 0.527, sellPricePerKwh: 0.429, roundTripEfficiency: 0.757 } },
+    },
+};
+await forecasts.publishBatteryForecast('battery-1', auto);
 ```
 
-Per-entry invariants:
+Invariants:
 
-- `seconds`: finite, non-negative; first entry `= 0`; subsequent entries strictly increasing.
-- `mode`: one of `charge` / `discharge` / `auto`.
-- `powerW`: finite, non-negative. **MUST be `0` when `mode === 'auto'`.**
+- `mode: 'auto'` must not carry a `relativeSchedule`. A `reason` must have a valid `type`; its `context.arbitrage` prices must be EUR/kWh within a plausible band (a ct value such as `35.2` is rejected), `roundTripEfficiency` must lie in (0, 1], and each window's start must lie before its end.
+- `seconds`: finite, non-negative; first entry `= 0`; strictly increasing; a multiple of the `resolution` step.
+- `direction`: one of `charge` / `discharge` / `idle`. `idle` hands the slot to the battery's own logic — to block charging or discharging, use that direction with `powerW = 0` instead.
+- `powerW`: finite, non-negative. **MUST be `0` when `direction === 'idle'`.**
 
 ### HeatpumpForecast
 
@@ -4190,6 +4283,14 @@ New reason types came with this surface, so a skipped row can say *why* instead
 
 **Battery first on PV surplus.** When a surplus consumer (EV on PV, heating rod, heat pump boost, surplus automation) is held back or reduced because the battery is charged first up to the owner's `batteryPvPriorityTargetSocPercent`, the energy manager states `BatteryPvPriority` (category `PvSurplus`) on that consumer: `context.batteryPvPriority.targetSocPercent` for the target, `socPercent` for the pack's current SoC and `powerW` for the surplus the battery is taking — e.g. "The battery charges to 40 % first (now 28 %)."
 
+**Battery trading: why or why not.** The `arbitrage` context (`EnyoDataBusCommandReasonArbitrageContext`) carries the trough-against-peak arithmetic behind a battery buy: `buyPricePerKwh` / `buyStartIso` / `buyEndIso`, `sellPricePerKwh` / `sellStartIso` / `sellEndIso`, `breakEvenPricePerKwh` (losses, wear and margin included) and `roundTripEfficiency` (a fraction, `0.757`). Prices are **EUR/kWh like every machine-readable price in the SDK** — `0.336`, not `33.6`. Three uses:
+
+- `PriceSpreadTooSmall` (category `EnergyPrice`) — the battery stays on Auto because buying in the trough and using the energy at the peak would not pay back: "Charging at 35.2 ct/kWh only pays off from 52.7 ct/kWh, but the peak averages 42.9 ct/kWh." Set `electricityPricePerKwh` to the buy price and all the figures; on a flat horizon send it without `arbitrage`. The trough is not "too expensive" — the gap is too small — so this is not `ElectricityPriceAboveThreshold`. Where PV makes Auto mean self-consumption, `SelfConsumptionOptimization` stays the right type.
+- `ElectricityPriceBelowThreshold` on a grid charge — the buy and the peak it is for: "Charging at 33.6 ct for the 17:00 peak at 43.7 ct."
+- `ScheduledOptimization` on a price hold (`Discharge 0`) — `sellStartIso` / `sellPricePerKwh`: "Stored energy kept for 17:00 (43.7 ct)." Not `ElectricityPriceBelowThreshold`, which would say power is cheap for a command that stops the battery.
+
+**Installation limits.** Power capped by a limit the owner or installer set — not the grid operator — carries `InstallationLimit` (category `Contention`) with `powerW` set to the ceiling and `context.installationLimit` = `{source, limitW}`, where `source` is `EnyoInstallationLimitSourceEnum.DesiredGridLimit` (`desiredKwLimit`) or `ChargerLimit` (`chargerLimitW`). `limitW` is in **W** even for the desired limit, which is configured in kW. `GridOperatorPowerLimitationActive` stays reserved for limits the grid operator imposed.
+
 **Grid-optimised charging.** A cost-optimised session placed in, or waiting for, a low-load hour because of `gridOptimizedEvCharging` carries `GridLoadOptimized` (category `Schedule`) with `context.placement` (chosen window and deadline) and `context.gridLoad` (`epexPricePerKwh`, `currency`). The EPEX price is a grid-load proxy, not what the customer pays, so the text must not promise a saving — e.g. "Charging from 02:00, when the grid is less busy — ready by 07:00."
 
 **Battery vs. heating rod.** When the owner set `heatingRodBatteryDischargeSocLimitPercent`, two reason types (category `BatteryState`) say whether the battery feeds the rod: `BatterySupportsHeatingRod` while it may (with `powerW` for its contribution), `BatteryReservedFromHeatingRod` once it reaches the floor. Both carry `context.batteryToHeatingRod.socLimitPercent` and `socPercent` — e.g. "Heating rod no longer runs from the battery — it is at your 80 % limit."

package/dist/cjs/implementations/appliance-command-forecast/appliance-command-forecast-validators.cjs

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ApplianceCommandForecastValidationError = void 0;
 exports.validateChargerForecast = validateChargerForecast;
 exports.validateBatteryCommandForecast = validateBatteryCommandForecast;
+exports.validateBatteryForecastReason = validateBatteryForecastReason;
 exports.validateHeatpumpForecast = validateHeatpumpForecast;
 exports.validateChargerSchedule = validateChargerSchedule;
 exports.validateBatterySchedule = validateBatterySchedule;
@@ -69,7 +70,9 @@ function validateChargerForecast(forecast) {
  * {@link BatteryCommandForecastModeEnum}: when `mode = 'auto'` no
  * schedule is expected; when `mode = 'schedule'` the embedded
  * {@link BatteryCommandForecastScheduled.relativeSchedule} is validated
- * by {@link validateBatterySchedule}.
+ * by {@link validateBatterySchedule}. An Auto forecast's optional
+ * {@link BatteryCommandForecastAuto.reason} is checked by
+ * {@link validateBatteryForecastReason}.
  */
 function validateBatteryCommandForecast(forecast) {
     if (!forecast || typeof forecast !== 'object') {
@@ -84,10 +87,75 @@ function validateBatteryCommandForecast(forecast) {
         if (forecast.relativeSchedule !== undefined) {
             throw new ApplianceCommandForecastValidationError("BatteryCommandForecast with mode='auto' must not carry a relativeSchedule.");
         }
+        if (forecast.reason !== undefined) {
+            validateBatteryForecastReason(forecast.reason, 'BatteryCommandForecast.reason');
+        }
         return;
     }
     validateBatterySchedule(forecast.relativeSchedule, forecast.resolution);
 }
+/**
+ * Lowest and highest plausible price per kWh in a reason's `arbitrage`
+ * context, in EUR/kWh. Wide enough for negative and spiking dynamic prices,
+ * narrow enough to catch a ct value (`33.6`) in a EUR field.
+ */
+const ARBITRAGE_PRICE_MIN_PER_KWH = -1;
+const ARBITRAGE_PRICE_MAX_PER_KWH = 5;
+/**
+ * Validates the reason attached to an Auto {@link BatteryCommandForecast}.
+ * Throws on the first violation.
+ *
+ * Checks that the reason is an object whose `type` is an
+ * {@link EnyoDataBusCommandReasonTypeEnum} member and, when it carries
+ * `context.arbitrage`, that:
+ * - every price is a finite EUR/kWh figure within a plausible band (catches
+ *   ct in a EUR field),
+ * - `roundTripEfficiency` lies in (0, 1] (catches `75.7` for `0.757`),
+ * - each window's start lies before its end, where both are given.
+ *
+ * @param reason - The reason to validate.
+ * @param fieldName - Field path used in error messages.
+ * @throws {ApplianceCommandForecastValidationError} On the first violation.
+ */
+function validateBatteryForecastReason(reason, fieldName) {
+    if (!reason || typeof reason !== 'object') {
+        throw new ApplianceCommandForecastValidationError(`${fieldName} must be an object.`);
+    }
+    validateEnumField(reason.type, Object.values(enyo_data_bus_value_js_1.EnyoDataBusCommandReasonTypeEnum), `${fieldName}.type`, true);
+    const arbitrage = reason.context?.arbitrage;
+    if (arbitrage === undefined)
+        return;
+    for (const key of ['buyPricePerKwh', 'sellPricePerKwh', 'breakEvenPricePerKwh']) {
+        const price = arbitrage[key];
+        if (price === undefined)
+            continue;
+        if (!Number.isFinite(price)) {
+            throw new ApplianceCommandForecastValidationError(`${fieldName}.context.arbitrage.${key} must be a finite number; got ${price}.`);
+        }
+        if (price < ARBITRAGE_PRICE_MIN_PER_KWH || price > ARBITRAGE_PRICE_MAX_PER_KWH) {
+            throw new ApplianceCommandForecastValidationError(`${fieldName}.context.arbitrage.${key} is ${price}, outside ` +
+                `${ARBITRAGE_PRICE_MIN_PER_KWH}…${ARBITRAGE_PRICE_MAX_PER_KWH} — prices are per kWh in ` +
+                'the reason\'s currency (EUR/kWh), not ct/kWh.');
+        }
+    }
+    const efficiency = arbitrage.roundTripEfficiency;
+    if (efficiency !== undefined && (!Number.isFinite(efficiency) || efficiency <= 0 || efficiency > 1)) {
+        throw new ApplianceCommandForecastValidationError(`${fieldName}.context.arbitrage.roundTripEfficiency is ${efficiency}; it is a fraction in (0, 1], ` +
+            'e.g. 0.757 rather than 75.7.');
+    }
+    for (const [start, end] of [['buyStartIso', 'buyEndIso'], ['sellStartIso', 'sellEndIso']]) {
+        const startIso = arbitrage[start];
+        const endIso = arbitrage[end];
+        for (const [key, iso] of [[start, startIso], [end, endIso]]) {
+            if (iso !== undefined && Number.isNaN(Date.parse(iso))) {
+                throw new ApplianceCommandForecastValidationError(`${fieldName}.context.arbitrage.${key} is not an ISO 8601 timestamp: ${iso}.`);
+            }
+        }
+        if (startIso !== undefined && endIso !== undefined && Date.parse(startIso) >= Date.parse(endIso)) {
+            throw new ApplianceCommandForecastValidationError(`${fieldName}.context.arbitrage.${start} must lie before ${end}.`);
+        }
+    }
+}
 /**
  * Validates a {@link HeatpumpForecast}. Throws on the first violation —
  * the error message names the offending field / index.

package/dist/cjs/implementations/appliance-command-forecast/appliance-command-forecast-validators.d.cts

@@ -1,4 +1,5 @@
 import { AirConditioningForecast, AirConditioningForecastScheduleEntry, ApplianceForecastResolutionEnum, BatteryCommandForecast, BatteryCommandForecastScheduleEntry, ChargerForecast, ChargerForecastScheduleEntry, HeatingRodForecast, HeatingRodForecastScheduleEntry, HeatpumpForecast, HeatpumpForecastScheduleEntry, SmartPlugForecast, SmartPlugForecastScheduleEntry } from '../../types/enyo-appliance-command-forecast.cjs';
+import { type EnyoDataBusCommandReason } from '../../types/enyo-data-bus-value.cjs';
 /**
  * Thrown when a forecast payload passed to one of the validators (or to
  * {@link EnergyAppApplianceEnergyManagerForecast.publishChargerForecast}
@@ -23,9 +24,28 @@ export declare function validateChargerForecast(forecast: ChargerForecast): void
  * {@link BatteryCommandForecastModeEnum}: when `mode = 'auto'` no
  * schedule is expected; when `mode = 'schedule'` the embedded
  * {@link BatteryCommandForecastScheduled.relativeSchedule} is validated
- * by {@link validateBatterySchedule}.
+ * by {@link validateBatterySchedule}. An Auto forecast's optional
+ * {@link BatteryCommandForecastAuto.reason} is checked by
+ * {@link validateBatteryForecastReason}.
  */
 export declare function validateBatteryCommandForecast(forecast: BatteryCommandForecast): void;
+/**
+ * Validates the reason attached to an Auto {@link BatteryCommandForecast}.
+ * Throws on the first violation.
+ *
+ * Checks that the reason is an object whose `type` is an
+ * {@link EnyoDataBusCommandReasonTypeEnum} member and, when it carries
+ * `context.arbitrage`, that:
+ * - every price is a finite EUR/kWh figure within a plausible band (catches
+ *   ct in a EUR field),
+ * - `roundTripEfficiency` lies in (0, 1] (catches `75.7` for `0.757`),
+ * - each window's start lies before its end, where both are given.
+ *
+ * @param reason - The reason to validate.
+ * @param fieldName - Field path used in error messages.
+ * @throws {ApplianceCommandForecastValidationError} On the first violation.
+ */
+export declare function validateBatteryForecastReason(reason: EnyoDataBusCommandReason, fieldName: string): void;
 /**
  * Validates a {@link HeatpumpForecast}. Throws on the first violation —
  * the error message names the offending field / index.

package/dist/cjs/implementations/heatpump/heatpump-control-session.cjs

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HeatpumpControlSessionTracker = exports.HeatpumpControlEndCauseEnum = void 0;
+exports.heatpumpControlActionKey = heatpumpControlActionKey;
+exports.heatpumpControlActionsKey = heatpumpControlActionsKey;
+/**
+ * Why a `HeatpumpControlV3` session ended — passed to
+ * `HeatpumpIntegrationEnergyApp.onHeatpumpControlEnded`.
+ */
+var HeatpumpControlEndCauseEnum;
+(function (HeatpumpControlEndCauseEnum) {
+    /** `validUntilIso` passed without a newer message (the energy manager stopped repeating it). */
+    HeatpumpControlEndCauseEnum["Expired"] = "expired";
+    /** The energy manager sent a `HeatpumpControlV3` with no actions and no power. */
+    HeatpumpControlEndCauseEnum["Ended"] = "ended";
+    /** The energy manager cancelled the session with `HeatpumpControlCancelV3`. */
+    HeatpumpControlEndCauseEnum["Cancelled"] = "cancelled";
+})(HeatpumpControlEndCauseEnum || (exports.HeatpumpControlEndCauseEnum = HeatpumpControlEndCauseEnum = {}));
+/**
+ * Key that identifies an action within a session — its target and zone index.
+ *
+ * @param action - The action.
+ * @returns E.g. `dhw:0`, or `room:` for an action without index.
+ */
+function heatpumpControlActionKey(action) {
+    return `${action.target}:${action.index ?? ''}`;
+}
+/**
+ * Stable key of a whole action list, independent of the order the actions
+ * were sent in. Two lists with the same key ask for the same thing.
+ *
+ * @param actions - The session's actions.
+ * @returns A string that changes whenever any action's target, index,
+ *   `deltaK` or `heatSource` changes.
+ */
+function heatpumpControlActionsKey(actions) {
+    return actions
+        .map((a) => [a.target, a.index ?? '', a.deltaK ?? '', a.heatSource ?? ''].join('|'))
+        .sort()
+        .join(';');
+}
+/**
+ * Tracks the `HeatpumpControlV3` session of each heatpump: which session is
+ * running, which of its actions have been applied, and when it lapses.
+ *
+ * Rules:
+ * - Same `sessionId` and same actions → the session continues; only
+ *   {@link HeatpumpControlSessionState.validUntilMs} moves.
+ * - New `sessionId` or changed actions → a fresh state; every action is
+ *   applied anew.
+ * - No new message by `validUntilIso` → the state is dropped and `onExpired`
+ *   is called for that appliance.
+ *
+ * Used by `HeatpumpIntegrationEnergyApp`; exported so integrations that
+ * override `handleHeatpumpControl` can reuse the same rules.
+ *
+ * @example
+ * ```typescript
+ * const tracker = new HeatpumpControlSessionTracker((applianceId) => resetHeatpump(applianceId));
+ * const {state, isNew} = tracker.track(message.applianceId, message.data);
+ * if (isNew) applyActions(message.data.actions);
+ * ```
+ */
+class HeatpumpControlSessionTracker {
+    onExpired;
+    now;
+    sessions = new Map();
+    timers = new Map();
+    /**
+     * @param onExpired - Called when an appliance's session lapses because no
+     *   message arrived by its `validUntilIso`. Not called by {@link end}.
+     * @param now - Clock in epoch milliseconds; injectable for tests.
+     */
+    constructor(onExpired, now = () => Date.now()) {
+        this.onExpired = onExpired;
+        this.now = now;
+    }
+    /**
+     * The current session state of an appliance, if one is running.
+     *
+     * @param applianceId - The heatpump appliance.
+     * @returns The state, or `undefined`.
+     */
+    get(applianceId) {
+        return this.sessions.get(applianceId);
+    }
+    /**
+     * Records a received session message and (re)arms its expiry.
+     *
+     * @param applianceId - The heatpump appliance the message is for.
+     * @param data - The message's data.
+     * @returns The appliance's state, and `isNew` when the session or its
+     *   actions changed — the moment to apply the actions anew.
+     * @throws {Error} When `validUntilIso` is not an ISO 8601 timestamp.
+     */
+    track(applianceId, data) {
+        const validUntilMs = Date.parse(data.validUntilIso);
+        if (!Number.isFinite(validUntilMs)) {
+            throw new Error(`validUntilIso is not an ISO 8601 timestamp: ${data.validUntilIso}`);
+        }
+        const actionsKey = heatpumpControlActionsKey(data.actions ?? []);
+        const current = this.sessions.get(applianceId);
+        const isNew = !current || current.sessionId !== data.sessionId || current.actionsKey !== actionsKey;
+        const state = isNew
+            ? { sessionId: data.sessionId, actionsKey, validUntilMs }
+            : { ...current, validUntilMs };
+        this.sessions.set(applianceId, state);
+        this.armExpiry(applianceId, validUntilMs);
+        return { state, isNew };
+    }
+    /**
+     * Ends an appliance's session without calling `onExpired` — for an
+     * explicit end the caller handles itself.
+     *
+     * @param applianceId - The heatpump appliance.
+     * @returns `true` when a session was running.
+     */
+    end(applianceId) {
+        this.clearTimer(applianceId);
+        return this.sessions.delete(applianceId);
+    }
+    /** Drops every session and timer. Call on shutdown. */
+    dispose() {
+        for (const applianceId of [...this.timers.keys()])
+            this.clearTimer(applianceId);
+        this.sessions.clear();
+    }
+    armExpiry(applianceId, validUntilMs) {
+        this.clearTimer(applianceId);
+        const delayMs = Math.max(0, validUntilMs - this.now());
+        this.timers.set(applianceId, setTimeout(() => {
+            this.timers.delete(applianceId);
+            const state = this.sessions.get(applianceId);
+            if (!state || state.validUntilMs > this.now())
+                return;
+            this.sessions.delete(applianceId);
+            this.onExpired(applianceId);
+        }, delayMs));
+    }
+    clearTimer(applianceId) {
+        const timer = this.timers.get(applianceId);
+        if (timer !== undefined)
+            clearTimeout(timer);
+        this.timers.delete(applianceId);
+    }
+}
+exports.HeatpumpControlSessionTracker = HeatpumpControlSessionTracker;

package/dist/cjs/implementations/heatpump/heatpump-control-session.d.cts

@@ -0,0 +1,107 @@
+import { EnyoDataBusHeatpumpControlV3, EnyoHeatpumpControlAction } from '../../types/enyo-data-bus-value.cjs';
+/**
+ * Why a `HeatpumpControlV3` session ended — passed to
+ * `HeatpumpIntegrationEnergyApp.onHeatpumpControlEnded`.
+ */
+export declare enum HeatpumpControlEndCauseEnum {
+    /** `validUntilIso` passed without a newer message (the energy manager stopped repeating it). */
+    Expired = "expired",
+    /** The energy manager sent a `HeatpumpControlV3` with no actions and no power. */
+    Ended = "ended",
+    /** The energy manager cancelled the session with `HeatpumpControlCancelV3`. */
+    Cancelled = "cancelled"
+}
+/**
+ * The state the SDK keeps for one heatpump's current `HeatpumpControlV3`
+ * session.
+ */
+export interface HeatpumpControlSessionState {
+    /** The session's `sessionId`. */
+    sessionId: string;
+    /** A stable key of the session's actions — changes when any action changes. */
+    actionsKey: string;
+    /** The latest `validUntilIso`, as epoch milliseconds. */
+    validUntilMs: number;
+}
+/**
+ * Key that identifies an action within a session — its target and zone index.
+ *
+ * @param action - The action.
+ * @returns E.g. `dhw:0`, or `room:` for an action without index.
+ */
+export declare function heatpumpControlActionKey(action: Pick<EnyoHeatpumpControlAction, 'target' | 'index'>): string;
+/**
+ * Stable key of a whole action list, independent of the order the actions
+ * were sent in. Two lists with the same key ask for the same thing.
+ *
+ * @param actions - The session's actions.
+ * @returns A string that changes whenever any action's target, index,
+ *   `deltaK` or `heatSource` changes.
+ */
+export declare function heatpumpControlActionsKey(actions: EnyoHeatpumpControlAction[]): string;
+/**
+ * Tracks the `HeatpumpControlV3` session of each heatpump: which session is
+ * running, which of its actions have been applied, and when it lapses.
+ *
+ * Rules:
+ * - Same `sessionId` and same actions → the session continues; only
+ *   {@link HeatpumpControlSessionState.validUntilMs} moves.
+ * - New `sessionId` or changed actions → a fresh state; every action is
+ *   applied anew.
+ * - No new message by `validUntilIso` → the state is dropped and `onExpired`
+ *   is called for that appliance.
+ *
+ * Used by `HeatpumpIntegrationEnergyApp`; exported so integrations that
+ * override `handleHeatpumpControl` can reuse the same rules.
+ *
+ * @example
+ * ```typescript
+ * const tracker = new HeatpumpControlSessionTracker((applianceId) => resetHeatpump(applianceId));
+ * const {state, isNew} = tracker.track(message.applianceId, message.data);
+ * if (isNew) applyActions(message.data.actions);
+ * ```
+ */
+export declare class HeatpumpControlSessionTracker {
+    private readonly onExpired;
+    private readonly now;
+    private readonly sessions;
+    private readonly timers;
+    /**
+     * @param onExpired - Called when an appliance's session lapses because no
+     *   message arrived by its `validUntilIso`. Not called by {@link end}.
+     * @param now - Clock in epoch milliseconds; injectable for tests.
+     */
+    constructor(onExpired: (applianceId: string) => void, now?: () => number);
+    /**
+     * The current session state of an appliance, if one is running.
+     *
+     * @param applianceId - The heatpump appliance.
+     * @returns The state, or `undefined`.
+     */
+    get(applianceId: string): HeatpumpControlSessionState | undefined;
+    /**
+     * Records a received session message and (re)arms its expiry.
+     *
+     * @param applianceId - The heatpump appliance the message is for.
+     * @param data - The message's data.
+     * @returns The appliance's state, and `isNew` when the session or its
+     *   actions changed — the moment to apply the actions anew.
+     * @throws {Error} When `validUntilIso` is not an ISO 8601 timestamp.
+     */
+    track(applianceId: string, data: EnyoDataBusHeatpumpControlV3['data']): {
+        state: HeatpumpControlSessionState;
+        isNew: boolean;
+    };
+    /**
+     * Ends an appliance's session without calling `onExpired` — for an
+     * explicit end the caller handles itself.
+     *
+     * @param applianceId - The heatpump appliance.
+     * @returns `true` when a session was running.
+     */
+    end(applianceId: string): boolean;
+    /** Drops every session and timer. Call on shutdown. */
+    dispose(): void;
+    private armExpiry;
+    private clearTimer;
+}