@enyo-energy/energy-app-sdk 1.28.0 → 1.30.0

package/README.md

@@ -1646,10 +1646,14 @@ A closed, SDK-defined set of user-facing controls the active energy manager hono
 | `BatteryEvDischargeMode` | `fixed-wh` \| `soc-limit` \| `intelligent` \| `block-discharge` \| `unmanaged` |
 | `BatteryEvDischargeFixedWh` | number, **Wh** (only under `fixed-wh`) |
 | `BatteryEvDischargeSocLimitPercent` | number, **%** floor (only under `soc-limit`) |
+| `BatteryPvPriorityTargetSocPercent` | number \| `null`, **%** target the battery is charged to from PV before other surplus consumers (absent / `null` = disabled) |
+| `BatteryDischargeBlockAboveHomeConsumptionW` | number \| `null`, **W** home consumption above which the battery may not discharge (absent / `null` = disabled) |
 | `HeatpumpControl` | boolean |
 | `HeatingRodControl` | boolean |
 | `HeatingRodMode` | `pv-surplus-only` \| `boost` |
+| `HeatingRodBatteryDischargeSocLimitPercent` | number \| `null`, **%** floor the battery may feed the heating rod down to (absent / `null` = disabled) |
 | `ChargerControl` | boolean |
+| `GridOptimizedEvCharging` | boolean, off by default — cost-optimised charging on a static / time-of-use tariff avoids high grid load (by EPEX spot) |
 | `DefaultChargeMode` | `EnyoChargeModeEnum` |
 | `PriceLimitMode` | `ct-per-kwh` \| `cheapest-share` (absent = no ceiling) |
 | `PriceLimitCtPerKwh` | number, **ct/kWh** (`7` = 7 ct/kWh; only under `ct-per-kwh`) |
@@ -1694,7 +1698,11 @@ Three things to get right:
 
 - **Absent is not `false`.** `undefined` means unsupported or never chosen; `false` means the user switched it off. Check `supported` first, then the value — collapsing the two steers hardware someone deliberately disabled.
 - **How the battery may feed a charging EV is one mode plus its parameter.** `BatteryEvDischargeMode` picks the strategy; `BatteryEvDischargeFixedWh` and `BatteryEvDischargeSocLimitPercent` are read only under their own mode. `block-discharge` (actively hold the battery back) and `unmanaged` (do not intervene either way) are **not** synonyms.
-- **Ten settings are gated by another** (`heatingRodMode` needs `heatingRodControl`, `priceLimitCtPerKwh` only applies under `priceLimitMode: 'ct-per-kwh'`, …). The tree is exported as `ENERGY_MANAGER_SETTING_DEPENDENCIES`, with two helpers over it: `getEnergyManagerSettingDependency(setting)` returns the direct gate and the value it must hold (or `null` for an ungated root), and `isEnergyManagerSettingActive(setting, values)` walks the whole chain — the gates are now two deep, so a Wh budget is live only when the mode is `fixed-wh` *and* battery control is on.
+- **Battery-first PV surplus is a charging target, not a floor.** `BatteryPvPriorityTargetSocPercent` (`40` = charge the battery to 40 % first) only holds back consumers that run *on surplus* — an EV on PV, a `pv-surplus-only` heating rod, heat pump surplus boosts, surplus automations. Grid-backed modes and explicit user requests are unaffected. It is independent of `BatteryEvDischargeSocLimitPercent`, which is a floor for discharging into the car. Disabled while absent or `null`; write `null` to switch it off again.
+- **The heating rod may draw from the battery only down to a floor, and only when asked.** `HeatingRodBatteryDischargeSocLimitPercent` (`80` = the rod may use the battery while it holds more than 80 %) is disabled while absent or `null`. It applies under both heating rod modes — under `pv-surplus-only` the battery above the floor counts as supply alongside PV, still never a grid import. It needs `batteryControl` to be enforced, and should not lie below `BatteryPvPriorityTargetSocPercent`; the validator warns on both. A consumer held back by it carries the command reason `BatteryPvPriority` (category `PvSurplus`) with `context.batteryPvPriority.targetSocPercent` and `socPercent`.
+- **The battery can be blocked from discharging under a heavy load.** `BatteryDischargeBlockAboveHomeConsumptionW` (`11000` = no discharge while the house draws more than 11 kW) keeps a sauna or an oven from emptying the battery in minutes. It is in **watts** — the validator warns below 100 W, which catches a kW value. Home consumption means the household plus every appliance the energy manager does **not** track — the same quantity as `homeConsumptionW` in the home consumption timeseries. Tracked appliances (wallbox, heat pump, heating rod, …) and the battery's own charging are excluded, so a charging car alone never trips the block. The block wins over the EV and heating rod discharge permissions; charging is unaffected. Disabled while absent or `null`. A battery held by it carries `HomeConsumptionHigh` with `context.batteryDischargeBlock.thresholdW` and `powerW` set to the current consumption.
+- **Grid-optimised EV charging is about the grid, not the bill.** `GridOptimizedEvCharging` adds no charge mode. It only affects `cost-optimized` sessions while the tariff is static or time-of-use (no effect under a dynamic one): the grid energy PV does not cover is placed in the hours with the lowest EPEX spot price before the deadline — the spot price as a proxy for grid load — instead of as late as possible or in the tariff's cheap windows. PV still comes first, the deadline still holds, and a session's price ceiling still applies against the customer's own tariff. On a time-of-use tariff a low-load hour can be a more expensive one; that is the trade the owner opts into.
+- **Fifteen settings are gated by another** (`heatingRodMode` needs `heatingRodControl`, `priceLimitCtPerKwh` only applies under `priceLimitMode: 'ct-per-kwh'`, …). The tree is exported as `ENERGY_MANAGER_SETTING_DEPENDENCIES`, with two helpers over it: `getEnergyManagerSettingDependency(setting)` returns the direct gate and the value it must hold (or `null` for an ungated root), and `isEnergyManagerSettingActive(setting, values)` walks the whole chain — the gates are now two deep, so a Wh budget is live only when the mode is `fixed-wh` *and* battery control is on.
 - **`priceLimitCtPerKwh` is in cents**, unlike the SDK's machine-readable price fields (`electricityPricePerKwh`, EUR/kWh). Divide by 100 when comparing. `validateEnergyManagerSettingsState()` warns on values outside a plausible ct band, which catches the mix-up.
 - **A price ceiling is one mode plus its parameter**, the same shape as the battery-to-EV one. `PriceLimitMode` picks how the ceiling is expressed — an absolute `ct-per-kwh` or a relative `cheapest-share` — and each value is read only under its own mode; the mode being absent means no ceiling at all. A relative ceiling ranks the price intervals *known* for the day and treats the cheapest `n` % as importable (the same rule as the `cheapest-share-of-day` automation trigger), so its effective threshold moves when tomorrow's prices publish — re-evaluate it rather than resolving it once.
 
@@ -3514,33 +3522,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
 
@@ -4180,6 +4213,20 @@ New reason types came with this surface, so a skipped row can say *why* instead
 
 **Battery vs. charging car.** While a car charges, the house battery is either held out of it or allowed to help, according to the owner's `batteryEvDischargeMode`. Two reason types (category `BatteryState`) say which: `BatteryReservedFromEv` for the hold (`Discharge 0`) and `BatterySupportsEvCharging` for the release (`mode=Auto`). Both carry `context.batteryToEv` (`EnyoDataBusCommandReasonBatteryToEvContext`) with the owner's `mode`, the hold `trigger` (`EnyoBatteryToEvHoldTriggerEnum`: `OwnerBlocked`, `SocLimitReached`, `AllowanceSpent`, `NoMeasurement`), `socLimitPercent`, `allowanceWh` and `remainingWh`. The energy manager re-checks a hold periodically by briefly releasing the battery; that re-check sets `batteryToEv.probe: true` and should not be listed as its own entry in a command history.
 
+**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."
+
 **Short-cycling protection.** When an appliance is kept running (or kept off) to honour its minimum on/off time, state `DeviceProtection` with `context.switching` (`EnyoDataBusCommandReasonSwitchingContext`): `hold` (`EnyoSwitchingProtectionHoldEnum.KeptOn` / `KeptOff`), `minOnSeconds`, `minOffSeconds` and `untilIso`. The text can then say "Kept running for another 4 minutes to protect the compressor" instead of a generic "Protecting the device".
 
 A hold that keeps an appliance **off** after a stop has its own type, `RestartDelay` (category `DeviceProtection`): set `context.switching` with `hold: KeptOff`, `minOffSeconds` and `untilIso` (when it may restart), and `powerW` to the power waiting for it — e.g. "Short pause after switching off — charging resumes at 13:15 so the car isn't switched on and off too often."

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/energy-manager-settings/energy-manager-settings-validators.cjs

@@ -67,6 +67,15 @@ const PRICE_LIMIT_MAX_CT = 200;
  * warned about for duplicating mode `block-discharge` rather than for being a unit slip.
  */
 const DISCHARGE_BUDGET_MIN_PLAUSIBLE_WH = 100;
+/**
+ * Below this, a
+ * {@link EnergyManagerSettingValues.batteryDischargeBlockAboveHomeConsumptionW}
+ * threshold is almost certainly kW entered into a W field.
+ *
+ * `11` would block the battery above 11 W — that is, whenever the house draws
+ * anything — where 11 kW was plainly meant. `0` is caught by the same check.
+ */
+const HOME_CONSUMPTION_BLOCK_MIN_PLAUSIBLE_W = 100;
 /** Every {@link EnergyManagerBatteryEvDischargeModeEnum} value. */
 const EV_DISCHARGE_MODES = new Set(Object.values(enyo_energy_manager_settings_js_1.EnergyManagerBatteryEvDischargeModeEnum));
 /** Value enums checked per field, for the enum-valued settings. */
@@ -139,6 +148,21 @@ function gateValue(values, setting) {
  *   duplicates mode `block-discharge`, the second catches a kWh value in a Wh field).
  * - `batteryEvDischargeSocLimitPercent` is a finite number in 0…100 (**error**),
  *   and not `100` (**warning** — a floor nothing can discharge past).
+ * - `batteryPvPriorityTargetSocPercent`, unless `null` (disabled), is a finite
+ *   number in 0…100 (**error**), and neither `0` (**warning** — no priority at
+ *   all, write `null`) nor `100` (**warning** — charging tapers near full, so
+ *   surplus consumers can be held back for hours).
+ * - `heatingRodBatteryDischargeSocLimitPercent`, unless `null` (disabled), is a
+ *   finite number in 0…100 (**error**), and not `100` (**warning** — a floor
+ *   nothing can discharge past). Set while `batteryControl` is not `true`
+ *   (**warning** — the floor cannot be enforced), or below
+ *   `batteryPvPriorityTargetSocPercent` (**warning** — the rod drains what the
+ *   PV priority refills).
+ * - `batteryDischargeBlockAboveHomeConsumptionW`, unless `null` (disabled), is
+ *   a finite non-negative number (**error**), and not below 100 W (**warning**
+ *   — catches a kW value in a W field; the battery would be blocked almost
+ *   always).
+ * - `null` counts as unset for the "stored" checks below.
  * - A parameter belonging to a mode other than the selected one is flagged by
  *   the gate check below, since {@link ENERGY_MANAGER_SETTING_DEPENDENCIES}
  *   gates each on its own mode.
@@ -184,7 +208,7 @@ function validateEnergyManagerSettingsState(state) {
     const values = state.values ?? {};
     // ── value formats ──────────────────────────────────────────────────────
     for (const key of ['batteryControl', 'batteryChargeFromGrid', 'heatpumpControl',
-        'heatingRodControl', 'chargerControl']) {
+        'heatingRodControl', 'chargerControl', 'gridOptimizedEvCharging']) {
         if (values[key] !== undefined && typeof values[key] !== 'boolean') {
             errors.push(`\`${key}\` must be a boolean when set.`);
         }
@@ -271,6 +295,67 @@ function validateEnergyManagerSettingsState(state) {
                 'states that intent directly.');
         }
     }
+    if (values.batteryPvPriorityTargetSocPercent !== undefined
+        && values.batteryPvPriorityTargetSocPercent !== null) {
+        const target = values.batteryPvPriorityTargetSocPercent;
+        if (typeof target !== 'number' || !Number.isFinite(target)) {
+            errors.push('`batteryPvPriorityTargetSocPercent` must be a finite number when set.');
+        }
+        else if (target < 0 || target > 100) {
+            errors.push(`\`batteryPvPriorityTargetSocPercent\` is ${target}; it is a percentage and must lie ` +
+                'between 0 and 100.');
+        }
+        else if (target === 0) {
+            warnings.push('`batteryPvPriorityTargetSocPercent` is 0, which gives the battery no priority at all — ' +
+                'write `null` to say that outright.');
+        }
+        else if (target === 100) {
+            warnings.push('`batteryPvPriorityTargetSocPercent` is 100. Charging tapers as the battery nears full, ' +
+                'so PV-surplus consumers may be held back for hours waiting for the last percent.');
+        }
+    }
+    if (values.batteryDischargeBlockAboveHomeConsumptionW !== undefined
+        && values.batteryDischargeBlockAboveHomeConsumptionW !== null) {
+        const threshold = values.batteryDischargeBlockAboveHomeConsumptionW;
+        if (typeof threshold !== 'number' || !Number.isFinite(threshold)) {
+            errors.push('`batteryDischargeBlockAboveHomeConsumptionW` must be a finite number or null when set.');
+        }
+        else if (threshold < 0) {
+            errors.push(`\`batteryDischargeBlockAboveHomeConsumptionW\` is ${threshold}; a consumption threshold ` +
+                'cannot be negative.');
+        }
+        else if (threshold < HOME_CONSUMPTION_BLOCK_MIN_PLAUSIBLE_W) {
+            warnings.push(`\`batteryDischargeBlockAboveHomeConsumptionW\` is ${threshold} W, so the battery would be ` +
+                'blocked almost always — this field is in watts, not kilowatts.');
+        }
+    }
+    if (values.heatingRodBatteryDischargeSocLimitPercent !== undefined
+        && values.heatingRodBatteryDischargeSocLimitPercent !== null) {
+        const floor = values.heatingRodBatteryDischargeSocLimitPercent;
+        if (typeof floor !== 'number' || !Number.isFinite(floor)) {
+            errors.push('`heatingRodBatteryDischargeSocLimitPercent` must be a finite number or null when set.');
+        }
+        else if (floor < 0 || floor > 100) {
+            errors.push(`\`heatingRodBatteryDischargeSocLimitPercent\` is ${floor}; it is a percentage and must lie ` +
+                'between 0 and 100.');
+        }
+        else {
+            if (floor === 100) {
+                warnings.push('`heatingRodBatteryDischargeSocLimitPercent` is 100, a floor the battery is already at, ' +
+                    'so the rod can never draw from it — write `null` to disable it outright.');
+            }
+            if (values.batteryControl !== true) {
+                warnings.push('`heatingRodBatteryDischargeSocLimitPercent` is set, but `batteryControl` is not true — ' +
+                    'the energy manager cannot hold the battery at the floor.');
+            }
+            const priority = values.batteryPvPriorityTargetSocPercent;
+            if (typeof priority === 'number' && Number.isFinite(priority) && floor < priority) {
+                warnings.push(`\`heatingRodBatteryDischargeSocLimitPercent\` (${floor} %) is below ` +
+                    `\`batteryPvPriorityTargetSocPercent\` (${priority} %) — the rod drains the battery ` +
+                    'into a range the PV priority then refills.');
+            }
+        }
+    }
     if (values.costOptimizedTargetTime !== undefined) {
         if (typeof values.costOptimizedTargetTime !== 'string'
             || !TIME_RE.test(values.costOptimizedTargetTime)) {
@@ -290,7 +375,7 @@ function validateEnergyManagerSettingsState(state) {
     // ── stored but unsupported ─────────────────────────────────────────────
     for (const setting of Object.values(enyo_energy_manager_settings_js_1.EnergyManagerSettingEnum)) {
         const keys = enyo_energy_manager_settings_js_1.ENERGY_MANAGER_SETTING_VALUE_KEYS[setting];
-        const held = keys.filter((key) => values[key] !== undefined);
+        const held = keys.filter((key) => values[key] !== undefined && values[key] !== null);
         if (held.length && !supported.has(setting)) {
             warnings.push(`"${setting}" holds a value (${held.join(', ')}) but is not in \`supported\` — ` +
                 'the energy manager will ignore it.');
@@ -301,7 +386,8 @@ function validateEnergyManagerSettingsState(state) {
         if (!dependency)
             continue;
         const key = setting;
-        const held = enyo_energy_manager_settings_js_1.ENERGY_MANAGER_SETTING_VALUE_KEYS[key].some((k) => values[k] !== undefined);
+        const held = enyo_energy_manager_settings_js_1.ENERGY_MANAGER_SETTING_VALUE_KEYS[key]
+            .some((k) => values[k] !== undefined && values[k] !== null);
         if (held && gateValue(values, dependency.requires) !== dependency.equals) {
             warnings.push(`"${key}" holds a value, but it only takes effect while "${dependency.requires}" ` +
                 `is ${JSON.stringify(dependency.equals)} — it currently cannot.`);

package/dist/cjs/implementations/energy-manager-settings/energy-manager-settings-validators.d.cts

@@ -65,6 +65,21 @@ export interface EnergyManagerSettingsValidationResult {
  *   duplicates mode `block-discharge`, the second catches a kWh value in a Wh field).
  * - `batteryEvDischargeSocLimitPercent` is a finite number in 0…100 (**error**),
  *   and not `100` (**warning** — a floor nothing can discharge past).
+ * - `batteryPvPriorityTargetSocPercent`, unless `null` (disabled), is a finite
+ *   number in 0…100 (**error**), and neither `0` (**warning** — no priority at
+ *   all, write `null`) nor `100` (**warning** — charging tapers near full, so
+ *   surplus consumers can be held back for hours).
+ * - `heatingRodBatteryDischargeSocLimitPercent`, unless `null` (disabled), is a
+ *   finite number in 0…100 (**error**), and not `100` (**warning** — a floor
+ *   nothing can discharge past). Set while `batteryControl` is not `true`
+ *   (**warning** — the floor cannot be enforced), or below
+ *   `batteryPvPriorityTargetSocPercent` (**warning** — the rod drains what the
+ *   PV priority refills).
+ * - `batteryDischargeBlockAboveHomeConsumptionW`, unless `null` (disabled), is
+ *   a finite non-negative number (**error**), and not below 100 W (**warning**
+ *   — catches a kW value in a W field; the battery would be blocked almost
+ *   always).
+ * - `null` counts as unset for the "stored" checks below.
  * - A parameter belonging to a mode other than the selected one is flagged by
  *   the gate check below, since {@link ENERGY_MANAGER_SETTING_DEPENDENCIES}
  *   gates each on its own mode.

package/dist/cjs/types/enyo-appliance-command-forecast.d.cts

@@ -47,6 +47,7 @@
 import { EnyoAirConditioningApplianceModeEnum, EnyoAirConditioningOptimizationModeEnum } from './enyo-air-conditioning-appliance.cjs';
 import { EnyoAutomationTriggerTypeEnum } from './enyo-automation.cjs';
 import { EnyoChargeModeEnum } from './enyo-data-bus-value.cjs';
+import type { EnyoDataBusCommandReason } from './enyo-data-bus-value.cjs';
 import { EnyoSmartPlugApplianceStateEnum } from './enyo-smart-plug-appliance.cjs';
 /**
  * Optional metadata describing the estimated savings of a forecasted
@@ -262,6 +263,17 @@ export interface BatteryCommandForecastScheduleEntry {
 export interface BatteryCommandForecastAuto extends ApplianceForecastMetadata {
     /** Discriminator — set to {@link BatteryCommandForecastModeEnum.Auto}. */
     mode: BatteryCommandForecastModeEnum.Auto;
+    /**
+     * Why no schedule is prescribed over the horizon — e.g.
+     * {@link EnyoDataBusCommandReasonTypeEnum.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 pick one. Optional, so a
+     * consumer that does not read it is unaffected — but without it an empty
+     * Auto forecast tends to read as "no forecast".
+     */
+    reason?: EnyoDataBusCommandReason;
 }
 /**
  * Forecast variant that declares an explicit relative schedule the