@enyo-energy/energy-app-sdk 0.0.198 → 1.0.0

package/README.md

@@ -1136,8 +1136,9 @@ A closed, SDK-defined set of user-facing controls the active energy manager hono
 | `BatteryControl` | boolean |
 | `BatteryChargingMode` | `paced` \| `immediate` |
 | `BatteryChargeFromGrid` | boolean |
-| `BatteryDischargeWhileChargingWh` | number \| `null` (Wh allowance; `null`/unset = disabled) |
-| `BlockBatteryDischargeWhileEvCharging` | boolean |
+| `BatteryEvDischargeMode` | `fixed-wh` \| `soc-limit` \| `intelligent` \| `block-discharge` \| `unmanaged` |
+| `BatteryEvDischargeFixedWh` | number, **Wh** (only under `fixed-wh`) |
+| `BatteryEvDischargeSocLimitPercent` | number, **%** floor (only under `soc-limit`) |
 | `HeatpumpControl` | boolean |
 | `HeatingRodControl` | boolean |
 | `HeatingRodMode` | `pv-surplus-only` \| `boost` |
@@ -1183,7 +1184,8 @@ em.unsubscribeEnergyManagerSettings(id);
 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.
-- **Six settings are gated by another** (`heatingRodMode` needs `heatingRodControl`, `priceLimitCtPerKwh` only applies under `price-limit`, …). The tree is exported as `ENERGY_MANAGER_SETTING_DEPENDENCIES` so the UI and the validator share one source of truth.
+- **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.
+- **Eight settings are gated by another** (`heatingRodMode` needs `heatingRodControl`, `priceLimitCtPerKwh` only applies under `price-limit`, …). 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.
 
 #### `useElectricityTariff(): EnergyAppElectricityTariff`

package/dist/cjs/energy-app-permission.type.cjs

@@ -1,6 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EnergyAppPermissionTypeEnum = void 0;
+/**
+ * All permissions an Energy App package can request.
+ *
+ * Source of truth for the permission catalogue — {@link EnergyAppPermissionType}
+ * is derived from it.
+ */
 var EnergyAppPermissionTypeEnum;
 (function (EnergyAppPermissionTypeEnum) {
     EnergyAppPermissionTypeEnum["RestrictedInternetAccess"] = "RestrictedInternetAccess";

package/dist/cjs/energy-app-permission.type.d.cts

@@ -1,4 +1,9 @@
-export type EnergyAppPermissionType = 'RestrictedInternetAccess' | 'NetworkDeviceDiscovery' | 'NetworkDeviceSearch' | 'NetworkDeviceAccess' | 'AllNetworkDeviceAccess' | 'Modbus' | 'Storage' | 'Appliance' | 'AllAppliances' | 'SendDataBusValues' | 'SubscribeDataBus' | 'SendDataBusCommands' | 'OcppServer' | 'ChargingCard' | 'Vehicle' | 'Charge' | 'SecretManager' | 'LocationZipCode' | 'LocationCoordinates' | 'Timeseries' | 'EnergyManagerInfo' | 'ElectricityTariff' | 'WeatherForecastRegister' | 'WeatherForecastUse' | 'PvForecastRegister' | 'PvForecastUse' | 'DynamicPriceForecastRegister' | 'DynamicPriceForecastUse' | 'PvSystemRegister' | 'PvSystemUse' | 'InverterControlCommands' | 'BatteryControlCommands' | 'BatteryStorageState' | 'ChargerControlCommands' | 'ModbusRtu' | 'EnergyPrices' | 'EnergyManager' | 'EebusDeviceManagement' | 'EebusDataAccess' | 'EebusControl' | 'Mqtt' | 'Bluetooth' | 'Wifi' | 'ChildProcess' | 'Udp' | 'ProvidedFiles' | 'Automation' | 'Savings' | 'EpexSpotPrices' | 'FirmwareRegistry';
+/**
+ * All permissions an Energy App package can request.
+ *
+ * Source of truth for the permission catalogue — {@link EnergyAppPermissionType}
+ * is derived from it.
+ */
 export declare enum EnergyAppPermissionTypeEnum {
     RestrictedInternetAccess = "RestrictedInternetAccess",
     NetworkDeviceDiscovery = "NetworkDeviceDiscovery",
@@ -52,3 +57,8 @@ export declare enum EnergyAppPermissionTypeEnum {
     EpexSpotPrices = "EpexSpotPrices",
     FirmwareRegistry = "FirmwareRegistry"
 }
+/**
+ * String union of every permission name, derived from
+ * {@link EnergyAppPermissionTypeEnum} so both spellings stay interchangeable.
+ */
+export type EnergyAppPermissionType = `${EnergyAppPermissionTypeEnum}`;

package/dist/cjs/implementations/energy-manager-settings/energy-manager-settings-utils.cjs

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * Lookups over the energy-manager settings gate tree.
+ *
+ * {@link ENERGY_MANAGER_SETTING_DEPENDENCIES} is the data; these are the two
+ * questions worth asking of it. Both exist so a cockpit, an energy manager and
+ * the validator answer them the same way instead of each restating the tree.
+ *
+ * The tree is not flat. `BatteryEvDischargeFixedWh` is gated on
+ * `BatteryEvDischargeMode`, which is itself gated on `BatteryControl` — so
+ * "which setting does this depend on" and "may this setting take effect right
+ * now" are genuinely different questions, and the second one has to walk.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getEnergyManagerSettingDependency = getEnergyManagerSettingDependency;
+exports.isEnergyManagerSettingActive = isEnergyManagerSettingActive;
+const enyo_energy_manager_settings_js_1 = require("../../types/enyo-energy-manager-settings.cjs");
+/**
+ * The setting a given setting depends on, and the value that gate must hold.
+ *
+ * Returns `null` for an ungated setting — `BatteryControl`, `HeatpumpControl`,
+ * `HeatingRodControl` and `ChargerControl` are the roots of the tree and depend
+ * on nothing.
+ *
+ * The gate's required *value* comes back with it, because the gate alone is not
+ * actionable: knowing `PriceLimitCtPerKwh` depends on `DefaultChargeMode` does
+ * not tell you it needs that mode to be `price-limit` specifically.
+ *
+ * Only the **direct** gate is returned, one level up. Use
+ * {@link isEnergyManagerSettingActive} to resolve a whole chain.
+ *
+ * @param setting - The setting to look up.
+ * @returns Its {@link EnergyManagerSettingDependency}, or `null` when ungated.
+ *
+ * @example
+ * ```typescript
+ * getEnergyManagerSettingDependency(EnergyManagerSettingEnum.HeatingRodMode);
+ * // → {requires: EnergyManagerSettingEnum.HeatingRodControl, equals: true}
+ *
+ * getEnergyManagerSettingDependency(EnergyManagerSettingEnum.BatteryEvDischargeFixedWh);
+ * // → {requires: EnergyManagerSettingEnum.BatteryEvDischargeMode, equals: 'fixed-wh'}
+ *
+ * getEnergyManagerSettingDependency(EnergyManagerSettingEnum.BatteryControl);
+ * // → null
+ * ```
+ */
+function getEnergyManagerSettingDependency(setting) {
+    return enyo_energy_manager_settings_js_1.ENERGY_MANAGER_SETTING_DEPENDENCIES[setting] ?? null;
+}
+/**
+ * Whether a setting can take effect given the values currently stored — the
+ * question a cockpit asks before rendering a control, and an energy manager asks
+ * before acting on one.
+ *
+ * Walks the whole chain, not just the direct gate: a fixed-Wh budget is live
+ * only when the mode is `fixed-wh` **and** battery control is on. Checking one
+ * level would report a budget as active under a mode whose own gate is closed.
+ *
+ * An ungated setting is always active. A gate that is unset (`undefined`) counts
+ * as not holding — consistent with the rest of this model, where absent is
+ * neither `true` nor `false` but "no choice was made".
+ *
+ * Says nothing about whether the setting is *supported*; check
+ * {@link EnergyManagerSettingsState.supported} for that. A setting can be
+ * perfectly active and still not implemented by the installed energy manager.
+ *
+ * @param setting - The setting to test.
+ * @param values - The currently stored values.
+ * @returns True when every gate above this setting holds.
+ *
+ * @example
+ * ```typescript
+ * const values = {
+ *     batteryControl: true,
+ *     batteryEvDischargeMode: EnergyManagerBatteryEvDischargeModeEnum.SocLimit,
+ * };
+ *
+ * isEnergyManagerSettingActive(EnergyManagerSettingEnum.BatteryEvDischargeSocLimitPercent, values);
+ * // → true
+ * isEnergyManagerSettingActive(EnergyManagerSettingEnum.BatteryEvDischargeFixedWh, values);
+ * // → false — the mode is soc-limit, so a Wh budget could never be spent
+ * ```
+ */
+function isEnergyManagerSettingActive(setting, values) {
+    // The tree is small and authored by hand, but a cycle would hang the walk —
+    // bound it by the number of settings rather than trusting the data.
+    const seen = new Set();
+    let current = setting;
+    while (current) {
+        if (seen.has(current))
+            return false;
+        seen.add(current);
+        const dependency = getEnergyManagerSettingDependency(current);
+        if (!dependency)
+            return true;
+        const [key] = enyo_energy_manager_settings_js_1.ENERGY_MANAGER_SETTING_VALUE_KEYS[dependency.requires];
+        if (!key || values[key] !== dependency.equals)
+            return false;
+        current = dependency.requires;
+    }
+    return true;
+}

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

@@ -0,0 +1,78 @@
+/**
+ * Lookups over the energy-manager settings gate tree.
+ *
+ * {@link ENERGY_MANAGER_SETTING_DEPENDENCIES} is the data; these are the two
+ * questions worth asking of it. Both exist so a cockpit, an energy manager and
+ * the validator answer them the same way instead of each restating the tree.
+ *
+ * The tree is not flat. `BatteryEvDischargeFixedWh` is gated on
+ * `BatteryEvDischargeMode`, which is itself gated on `BatteryControl` — so
+ * "which setting does this depend on" and "may this setting take effect right
+ * now" are genuinely different questions, and the second one has to walk.
+ */
+import type { EnergyManagerSettingDependency, EnergyManagerSettingEnum, EnergyManagerSettingValues } from '../../types/enyo-energy-manager-settings.cjs';
+/**
+ * The setting a given setting depends on, and the value that gate must hold.
+ *
+ * Returns `null` for an ungated setting — `BatteryControl`, `HeatpumpControl`,
+ * `HeatingRodControl` and `ChargerControl` are the roots of the tree and depend
+ * on nothing.
+ *
+ * The gate's required *value* comes back with it, because the gate alone is not
+ * actionable: knowing `PriceLimitCtPerKwh` depends on `DefaultChargeMode` does
+ * not tell you it needs that mode to be `price-limit` specifically.
+ *
+ * Only the **direct** gate is returned, one level up. Use
+ * {@link isEnergyManagerSettingActive} to resolve a whole chain.
+ *
+ * @param setting - The setting to look up.
+ * @returns Its {@link EnergyManagerSettingDependency}, or `null` when ungated.
+ *
+ * @example
+ * ```typescript
+ * getEnergyManagerSettingDependency(EnergyManagerSettingEnum.HeatingRodMode);
+ * // → {requires: EnergyManagerSettingEnum.HeatingRodControl, equals: true}
+ *
+ * getEnergyManagerSettingDependency(EnergyManagerSettingEnum.BatteryEvDischargeFixedWh);
+ * // → {requires: EnergyManagerSettingEnum.BatteryEvDischargeMode, equals: 'fixed-wh'}
+ *
+ * getEnergyManagerSettingDependency(EnergyManagerSettingEnum.BatteryControl);
+ * // → null
+ * ```
+ */
+export declare function getEnergyManagerSettingDependency(setting: EnergyManagerSettingEnum): EnergyManagerSettingDependency | null;
+/**
+ * Whether a setting can take effect given the values currently stored — the
+ * question a cockpit asks before rendering a control, and an energy manager asks
+ * before acting on one.
+ *
+ * Walks the whole chain, not just the direct gate: a fixed-Wh budget is live
+ * only when the mode is `fixed-wh` **and** battery control is on. Checking one
+ * level would report a budget as active under a mode whose own gate is closed.
+ *
+ * An ungated setting is always active. A gate that is unset (`undefined`) counts
+ * as not holding — consistent with the rest of this model, where absent is
+ * neither `true` nor `false` but "no choice was made".
+ *
+ * Says nothing about whether the setting is *supported*; check
+ * {@link EnergyManagerSettingsState.supported} for that. A setting can be
+ * perfectly active and still not implemented by the installed energy manager.
+ *
+ * @param setting - The setting to test.
+ * @param values - The currently stored values.
+ * @returns True when every gate above this setting holds.
+ *
+ * @example
+ * ```typescript
+ * const values = {
+ *     batteryControl: true,
+ *     batteryEvDischargeMode: EnergyManagerBatteryEvDischargeModeEnum.SocLimit,
+ * };
+ *
+ * isEnergyManagerSettingActive(EnergyManagerSettingEnum.BatteryEvDischargeSocLimitPercent, values);
+ * // → true
+ * isEnergyManagerSettingActive(EnergyManagerSettingEnum.BatteryEvDischargeFixedWh, values);
+ * // → false — the mode is soc-limit, so a Wh budget could never be spent
+ * ```
+ */
+export declare function isEnergyManagerSettingActive(setting: EnergyManagerSettingEnum, values: EnergyManagerSettingValues): boolean;

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

@@ -59,15 +59,16 @@ const TIME_RE = /^([01]\d|2[0-3]):[0-5]\d$/;
 const PRICE_LIMIT_MIN_CT = -100;
 const PRICE_LIMIT_MAX_CT = 200;
 /**
- * Below this, a {@link EnergyManagerSettingValues.batteryDischargeWhileChargingWh}
+ * Below this, a {@link EnergyManagerSettingValues.batteryEvDischargeFixedWh}
  * budget is almost certainly kWh entered into a Wh field.
  *
- * `10` would be ten watt-hours — a rounding error against any house battery, and
- * indistinguishable from "no discharge at all" in practice, where `10` kWh was
- * plainly meant. `0` is exempt: it is a legitimate, if roundabout, way to say
- * disabled.
+ * `10` would be ten watt-hours — a rounding error against any house battery,
+ * where `10` kWh was plainly meant. `0` is handled separately: it is legal, and
+ * warned about for duplicating mode `block-discharge` rather than for being a unit slip.
  */
 const DISCHARGE_BUDGET_MIN_PLAUSIBLE_WH = 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. */
 const BATTERY_CHARGING_MODES = new Set(Object.values(enyo_energy_manager_settings_js_1.EnergyManagerBatteryChargingModeEnum));
 const HEATING_ROD_MODES = new Set(Object.values(enyo_energy_manager_settings_js_1.EnergyManagerHeatingRodModeEnum));
@@ -115,12 +116,15 @@ function gateValue(values, setting) {
  *   zone the runtime resolves (**error**).
  * - `priceLimitCtPerKwh` is a finite number (**error**), and lies in a plausible
  *   ct/kWh band (**warning** — catches a EUR/kWh value in a ct/kWh field).
- * - `batteryDischargeWhileChargingWh` is a finite non-negative number or `null`
- *   (**error**), and is not a negligible positive figure (**warning** — catches
- *   a kWh value in a Wh field).
- * - `blockBatteryDischargeWhileEvCharging` does not sit alongside a positive
- *   `batteryDischargeWhileChargingWh` budget (**warning** — the block overrides
- *   the budget, so it could never be spent).
+ * - `batteryEvDischargeMode` holds an enum member (**error**).
+ * - `batteryEvDischargeFixedWh` is a finite non-negative number (**error**), and
+ *   is neither `0` nor a negligible positive figure (**warning** — the first
+ *   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).
+ * - 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.
  * - A value stored for an unsupported setting (**warning** — the energy manager
  *   will ignore it).
  * - A value stored while its gate does not hold (**warning** — it can never take
@@ -162,8 +166,7 @@ function validateEnergyManagerSettingsState(state) {
     }
     const values = state.values ?? {};
     // ── value formats ──────────────────────────────────────────────────────
-    for (const key of ['batteryControl', 'batteryChargeFromGrid',
-        'blockBatteryDischargeWhileEvCharging', 'heatpumpControl',
+    for (const key of ['batteryControl', 'batteryChargeFromGrid', 'heatpumpControl',
         'heatingRodControl', 'chargerControl']) {
         if (values[key] !== undefined && typeof values[key] !== 'boolean') {
             errors.push(`\`${key}\` must be a boolean when set.`);
@@ -191,27 +194,44 @@ function validateEnergyManagerSettingsState(state) {
                 'cents per kWh, not EUR per kWh.');
         }
     }
-    if (values.batteryDischargeWhileChargingWh !== undefined
-        && values.batteryDischargeWhileChargingWh !== null) {
-        const budget = values.batteryDischargeWhileChargingWh;
+    if (values.batteryEvDischargeMode !== undefined
+        && !EV_DISCHARGE_MODES.has(values.batteryEvDischargeMode)) {
+        errors.push(`\`batteryEvDischargeMode\` "${values.batteryEvDischargeMode}" is not an ` +
+            'EnergyManagerBatteryEvDischargeModeEnum member.');
+    }
+    if (values.batteryEvDischargeFixedWh !== undefined) {
+        const budget = values.batteryEvDischargeFixedWh;
         if (typeof budget !== 'number' || !Number.isFinite(budget)) {
-            errors.push('`batteryDischargeWhileChargingWh` must be a finite number or `null` when set.');
+            errors.push('`batteryEvDischargeFixedWh` must be a finite number when set.');
         }
         else if (budget < 0) {
-            errors.push(`\`batteryDischargeWhileChargingWh\` is ${budget}; a discharge budget cannot be ` +
-                'negative. Use `null` to disable the transfer entirely.');
+            errors.push(`\`batteryEvDischargeFixedWh\` is ${budget}; a budget cannot be negative. ` +
+                `Use mode "${enyo_energy_manager_settings_js_1.EnergyManagerBatteryEvDischargeModeEnum.BlockDischarge}" to forbid the transfer.`);
+        }
+        else if (budget === 0) {
+            warnings.push('`batteryEvDischargeFixedWh` is 0, which says the same as mode ' +
+                `"${enyo_energy_manager_settings_js_1.EnergyManagerBatteryEvDischargeModeEnum.BlockDischarge}" — prefer the mode, which says it ` +
+                'where a reader will look.');
         }
-        else if (budget > 0 && budget < DISCHARGE_BUDGET_MIN_PLAUSIBLE_WH) {
-            warnings.push(`\`batteryDischargeWhileChargingWh\` is ${budget} Wh, which is negligible against ` +
-                'any house battery — this field is in watt-hours, not kilowatt-hours.');
+        else if (budget < DISCHARGE_BUDGET_MIN_PLAUSIBLE_WH) {
+            warnings.push(`\`batteryEvDischargeFixedWh\` is ${budget} Wh, which is negligible against any ` +
+                'house battery — this field is in watt-hours, not kilowatt-hours.');
         }
     }
-    if (values.blockBatteryDischargeWhileEvCharging === true
-        && typeof values.batteryDischargeWhileChargingWh === 'number'
-        && values.batteryDischargeWhileChargingWh > 0) {
-        warnings.push('`blockBatteryDischargeWhileEvCharging` is true, which closes the tap entirely, so the ' +
-            `\`batteryDischargeWhileChargingWh\` budget of ${values.batteryDischargeWhileChargingWh} Wh ` +
-            'can never be spent. Clear one of the two.');
+    if (values.batteryEvDischargeSocLimitPercent !== undefined) {
+        const soc = values.batteryEvDischargeSocLimitPercent;
+        if (typeof soc !== 'number' || !Number.isFinite(soc)) {
+            errors.push('`batteryEvDischargeSocLimitPercent` must be a finite number when set.');
+        }
+        else if (soc < 0 || soc > 100) {
+            errors.push(`\`batteryEvDischargeSocLimitPercent\` is ${soc}; it is a percentage and must lie ` +
+                'between 0 and 100.');
+        }
+        else if (soc === 100) {
+            warnings.push('`batteryEvDischargeSocLimitPercent` is 100, a floor the battery is already at, so ' +
+                `nothing can ever be discharged — mode "${enyo_energy_manager_settings_js_1.EnergyManagerBatteryEvDischargeModeEnum.BlockDischarge}" ` +
+                'states that intent directly.');
+        }
     }
     if (values.costOptimizedTargetTime !== undefined) {
         if (typeof values.costOptimizedTargetTime !== 'string'

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

@@ -56,12 +56,15 @@ export interface EnergyManagerSettingsValidationResult {
  *   zone the runtime resolves (**error**).
  * - `priceLimitCtPerKwh` is a finite number (**error**), and lies in a plausible
  *   ct/kWh band (**warning** — catches a EUR/kWh value in a ct/kWh field).
- * - `batteryDischargeWhileChargingWh` is a finite non-negative number or `null`
- *   (**error**), and is not a negligible positive figure (**warning** — catches
- *   a kWh value in a Wh field).
- * - `blockBatteryDischargeWhileEvCharging` does not sit alongside a positive
- *   `batteryDischargeWhileChargingWh` budget (**warning** — the block overrides
- *   the budget, so it could never be spent).
+ * - `batteryEvDischargeMode` holds an enum member (**error**).
+ * - `batteryEvDischargeFixedWh` is a finite non-negative number (**error**), and
+ *   is neither `0` nor a negligible positive figure (**warning** — the first
+ *   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).
+ * - 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.
  * - A value stored for an unsupported setting (**warning** — the energy manager
  *   will ignore it).
  * - A value stored while its gate does not hold (**warning** — it can never take

package/dist/cjs/implementations/onboarding-v2/onboarding-v2-validators.cjs

@@ -147,6 +147,7 @@ function validateOnboardingGuideV2(guide, context) {
             `"${enyo_onboarding_v2_js_1.EnyoOnboardingV2PauseReason.EnyoTodo}" when enyo takes the setup over.`);
     }
     validateNetworkScanFlag(guide, warnings);
+    validateApplianceBinding(guide, errors, warnings);
     return { ok: errors.length === 0, errors, warnings };
 }
 /**
@@ -645,6 +646,41 @@ function validateAdditionalSetupBlocks(step, at, errors, warnings) {
         }
     }
 }
+/**
+ * Checks {@link EnyoOnboardingV2Guide.applianceId} against the guide's
+ * {@link EnyoOnboardingV2Guide.startVariant}.
+ *
+ * The binding is required on {@link EnyoOnboardingV2StartVariant.Maintenance}
+ * and meaningless everywhere else. A maintenance run services an appliance that
+ * already exists, so a guide that does not name one cannot be bound to anything
+ * — that is a blocking error, not advice. The reverse is only a warning: an
+ * installation guide carrying an appliance id is harmless, the host ignores it,
+ * but it is a sign the wrong variant was chosen.
+ *
+ * @param guide - The guide being validated.
+ * @param errors - Collector for blocking problems.
+ * @param warnings - Collector for advisory problems.
+ */
+function validateApplianceBinding(guide, errors, warnings) {
+    const isMaintenance = guide.startVariant === enyo_onboarding_v2_js_1.EnyoOnboardingV2StartVariant.Maintenance;
+    const applianceId = typeof guide.applianceId === 'string' ? guide.applianceId.trim() : undefined;
+    if (isMaintenance) {
+        if (!applianceId) {
+            errors.push('`applianceId` is required on a `' +
+                `${enyo_onboarding_v2_js_1.EnyoOnboardingV2StartVariant.Maintenance}` +
+                '` guide — a maintenance run services an appliance that already exists, so the ' +
+                'guide must name it.');
+        }
+        return;
+    }
+    if (applianceId) {
+        warnings.push('`applianceId` is set on a `' +
+            `${guide.startVariant}` +
+            '` guide and is ignored — only a `' +
+            `${enyo_onboarding_v2_js_1.EnyoOnboardingV2StartVariant.Maintenance}` +
+            '` guide binds an existing appliance.');
+    }
+}
 /**
  * Checks {@link EnyoOnboardingV2Guide.requiresNetworkScan} against what the guide
  * actually does.

package/dist/cjs/index.cjs

@@ -42,6 +42,7 @@ __exportStar(require("./types/enyo-energy-manager.cjs"), exports);
 __exportStar(require("./packages/energy-app-energy-manager.cjs"), exports);
 __exportStar(require("./types/enyo-energy-manager-settings.cjs"), exports);
 __exportStar(require("./implementations/energy-manager-settings/energy-manager-settings-validators.cjs"), exports);
+__exportStar(require("./implementations/energy-manager-settings/energy-manager-settings-utils.cjs"), exports);
 __exportStar(require("./types/enyo-electricity-tariff.cjs"), exports);
 __exportStar(require("./packages/energy-app-electricity-tariff.cjs"), exports);
 __exportStar(require("./types/enyo-pv-forecast.cjs"), exports);

package/dist/cjs/index.d.cts

@@ -26,6 +26,7 @@ export * from './types/enyo-energy-manager.cjs';
 export * from './packages/energy-app-energy-manager.cjs';
 export * from './types/enyo-energy-manager-settings.cjs';
 export * from './implementations/energy-manager-settings/energy-manager-settings-validators.cjs';
+export * from './implementations/energy-manager-settings/energy-manager-settings-utils.cjs';
 export * from './types/enyo-electricity-tariff.cjs';
 export * from './packages/energy-app-electricity-tariff.cjs';
 export * from './types/enyo-pv-forecast.cjs';

package/dist/cjs/types/enyo-energy-manager-settings.cjs

@@ -27,7 +27,7 @@
  * (`../implementations/energy-manager-settings/energy-manager-settings-validators.ts`).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ENERGY_MANAGER_SETTING_VALUE_KEYS = exports.ENERGY_MANAGER_SETTING_DEPENDENCIES = exports.EnergyManagerHeatingRodModeEnum = exports.EnergyManagerBatteryChargingModeEnum = exports.EnergyManagerSettingEnum = void 0;
+exports.ENERGY_MANAGER_SETTING_VALUE_KEYS = exports.ENERGY_MANAGER_SETTING_DEPENDENCIES = exports.EnergyManagerHeatingRodModeEnum = exports.EnergyManagerBatteryEvDischargeModeEnum = exports.EnergyManagerBatteryChargingModeEnum = exports.EnergyManagerSettingEnum = void 0;
 /**
  * The general settings an energy manager can honour.
  *
@@ -44,10 +44,12 @@ var EnergyManagerSettingEnum;
     EnergyManagerSettingEnum["BatteryChargingMode"] = "battery-charging-mode";
     /** Whether the battery may be charged from the grid, not only from PV surplus. */
     EnergyManagerSettingEnum["BatteryChargeFromGrid"] = "battery-charge-from-grid";
-    /** How much energy the battery may discharge into a charging vehicle, in Wh. Unset/`null` disables it. */
-    EnergyManagerSettingEnum["BatteryDischargeWhileChargingWh"] = "battery-discharge-while-charging-wh";
-    /** Hard block on battery discharge into a charging vehicle. Overrides any Wh allowance. */
-    EnergyManagerSettingEnum["BlockBatteryDischargeWhileEvCharging"] = "block-battery-discharge-while-ev-charging";
+    /** How the battery may feed a charging vehicle — see {@link EnergyManagerBatteryEvDischargeModeEnum}. */
+    EnergyManagerSettingEnum["BatteryEvDischargeMode"] = "battery-ev-discharge-mode";
+    /** The per-session budget, in Wh. Only under {@link EnergyManagerBatteryEvDischargeModeEnum.FixedWh}. */
+    EnergyManagerSettingEnum["BatteryEvDischargeFixedWh"] = "battery-ev-discharge-fixed-wh";
+    /** The SoC floor, in %. Only under {@link EnergyManagerBatteryEvDischargeModeEnum.SocLimit}. */
+    EnergyManagerSettingEnum["BatteryEvDischargeSocLimitPercent"] = "battery-ev-discharge-soc-limit-percent";
     // ── Heat pump ──────────────────────────────────────────────────────────
     /** Whether the energy manager may steer the heat pump. */
     EnergyManagerSettingEnum["HeatpumpControl"] = "heatpump-control";
@@ -86,6 +88,64 @@ var EnergyManagerBatteryChargingModeEnum;
      */
     EnergyManagerBatteryChargingModeEnum["Immediate"] = "immediate";
 })(EnergyManagerBatteryChargingModeEnum || (exports.EnergyManagerBatteryChargingModeEnum = EnergyManagerBatteryChargingModeEnum = {}));
+/**
+ * How the house battery may feed a vehicle that is charging.
+ *
+ * Replaces the earlier pair of a boolean block and a nullable Wh budget. That
+ * shape could express "off" two ways and had no room for the answers installers
+ * actually want — drain to a floor, or let enyo work it out — so the strategy is
+ * now named once here and its parameter lives in a separate setting.
+ *
+ * Read {@link None} and {@link Unmanaged} carefully: they are not synonyms, and
+ * confusing them is the difference between the energy manager holding the
+ * battery back and it simply not looking.
+ */
+var EnergyManagerBatteryEvDischargeModeEnum;
+(function (EnergyManagerBatteryEvDischargeModeEnum) {
+    /**
+     * Allow a fixed budget per session, given by
+     * {@link EnergyManagerSettingValues.batteryEvDischargeFixedWh}.
+     *
+     * The plain answer to "how much of my house battery may go into the car" —
+     * an amount, spent and then stopped.
+     */
+    EnergyManagerBatteryEvDischargeModeEnum["FixedWh"] = "fixed-wh";
+    /**
+     * Discharge into the vehicle until the battery reaches the floor given by
+     * {@link EnergyManagerSettingValues.batteryEvDischargeSocLimitPercent}.
+     *
+     * The same intent as {@link FixedWh} expressed in the unit owners actually
+     * reason in — "keep half the battery for the house" survives a change of
+     * battery, where a watt-hour figure does not.
+     */
+    EnergyManagerBatteryEvDischargeModeEnum["SocLimit"] = "soc-limit";
+    /**
+     * Let enyo decide, session by session.
+     *
+     * The energy manager weighs price, forecast, house load and departure time
+     * instead of following a fixed rule. Nothing further to configure — the
+     * other two settings carry no meaning here.
+     */
+    EnergyManagerBatteryEvDischargeModeEnum["Intelligent"] = "intelligent";
+    /**
+     * Never discharge the battery into a vehicle. The energy manager actively
+     * holds it back.
+     *
+     * This is an instruction, not an absence of one — contrast {@link Unmanaged},
+     * which is the absence. Named for what it does rather than for the amount it
+     * permits, so that the two cannot be read as the same answer.
+     */
+    EnergyManagerBatteryEvDischargeModeEnum["BlockDischarge"] = "block-discharge";
+    /**
+     * The energy manager does not manage this flow at all.
+     *
+     * It neither permits nor prevents: whatever the hardware does on its own
+     * stands, and the battery may well end up feeding the car as a side effect.
+     * Choose this when something else owns the decision, never as a way to
+     * express "no discharge" — that is {@link BlockDischarge}.
+     */
+    EnergyManagerBatteryEvDischargeModeEnum["Unmanaged"] = "unmanaged";
+})(EnergyManagerBatteryEvDischargeModeEnum || (exports.EnergyManagerBatteryEvDischargeModeEnum = EnergyManagerBatteryEvDischargeModeEnum = {}));
 /**
  * What the heating rod is allowed to do.
  *
@@ -131,13 +191,17 @@ exports.ENERGY_MANAGER_SETTING_DEPENDENCIES = {
         requires: EnergyManagerSettingEnum.BatteryControl,
         equals: true,
     },
-    [EnergyManagerSettingEnum.BatteryDischargeWhileChargingWh]: {
+    [EnergyManagerSettingEnum.BatteryEvDischargeMode]: {
         requires: EnergyManagerSettingEnum.BatteryControl,
         equals: true,
     },
-    [EnergyManagerSettingEnum.BlockBatteryDischargeWhileEvCharging]: {
-        requires: EnergyManagerSettingEnum.BatteryControl,
-        equals: true,
+    [EnergyManagerSettingEnum.BatteryEvDischargeFixedWh]: {
+        requires: EnergyManagerSettingEnum.BatteryEvDischargeMode,
+        equals: EnergyManagerBatteryEvDischargeModeEnum.FixedWh,
+    },
+    [EnergyManagerSettingEnum.BatteryEvDischargeSocLimitPercent]: {
+        requires: EnergyManagerSettingEnum.BatteryEvDischargeMode,
+        equals: EnergyManagerBatteryEvDischargeModeEnum.SocLimit,
     },
     [EnergyManagerSettingEnum.HeatingRodMode]: {
         requires: EnergyManagerSettingEnum.HeatingRodControl,
@@ -167,8 +231,9 @@ exports.ENERGY_MANAGER_SETTING_VALUE_KEYS = {
     [EnergyManagerSettingEnum.BatteryControl]: ['batteryControl'],
     [EnergyManagerSettingEnum.BatteryChargingMode]: ['batteryChargingMode'],
     [EnergyManagerSettingEnum.BatteryChargeFromGrid]: ['batteryChargeFromGrid'],
-    [EnergyManagerSettingEnum.BatteryDischargeWhileChargingWh]: ['batteryDischargeWhileChargingWh'],
-    [EnergyManagerSettingEnum.BlockBatteryDischargeWhileEvCharging]: ['blockBatteryDischargeWhileEvCharging'],
+    [EnergyManagerSettingEnum.BatteryEvDischargeMode]: ['batteryEvDischargeMode'],
+    [EnergyManagerSettingEnum.BatteryEvDischargeFixedWh]: ['batteryEvDischargeFixedWh'],
+    [EnergyManagerSettingEnum.BatteryEvDischargeSocLimitPercent]: ['batteryEvDischargeSocLimitPercent'],
     [EnergyManagerSettingEnum.HeatpumpControl]: ['heatpumpControl'],
     [EnergyManagerSettingEnum.HeatingRodControl]: ['heatingRodControl'],
     [EnergyManagerSettingEnum.HeatingRodMode]: ['heatingRodMode'],