@enyo-energy/energy-app-sdk 0.0.195 → 0.0.197

package/README.md

@@ -172,7 +172,8 @@ The SDK exposes several layered building blocks. Pick the one that matches the k
 | Manage electricity tariffs (default tariff, price per kWh) | [`useElectricityTariff()`](#useelectricitytariff-energyappelectricitytariff) |
 | Register a PV system (kWp, DC strings, orientation) | [`usePvSystem()`](#usepvsystem-energyapppvsystem) |
 | Discover capabilities of the active energy manager | [`useEnergyManager()`](#useenergymanager-energyappenergymanager) |
-| Drive a multi-step onboarding flow | [`useOnboarding()`](#useonboarding-energyapponboarding) |
+| Serve your v2 onboarding guides when the host asks for them | [`useOnboardingV2()`](#useonboardingv2-energyapponboardingv2) |
+| Drive a multi-step onboarding flow (v1, deprecated) | [`useOnboarding()`](#useonboarding-energyapponboarding) |
 | Allocate process-local sequential IDs | [`useSequenceGenerator()`](#usesequencegenerator-energyappsequencegenerator) |
 | Manage retries with circuit-breaker semantics | [`RetryManager`](#retry-framework) |
 | Keep an `applianceId` cache in sync with the SDK | [`ApplianceManager`](#appliance-management) |
@@ -1126,6 +1127,65 @@ if (info) console.log(`Active manager: ${info.name} v${info.version}`);
 
 Requires the `EnergyManagerInfo` permission.
 
+##### General settings
+
+A closed, SDK-defined set of user-facing controls the active energy manager honours — the contract between the enyo cockpit and whichever manager is installed. Not to be confused with `useSettings()`, which is per-package, string-valued, and rendered on your own config screen.
+
+| Setting | Type |
+|---|---|
+| `BatteryControl` | boolean |
+| `BatteryChargingMode` | `paced` \| `immediate` |
+| `BatteryChargeFromGrid` | boolean |
+| `BatteryDischargeWhileChargingWh` | number \| `null` (Wh allowance; `null`/unset = disabled) |
+| `BlockBatteryDischargeWhileEvDischarging` | boolean |
+| `HeatpumpControl` | boolean |
+| `HeatingRodControl` | boolean |
+| `HeatingRodMode` | `pv-surplus-only` \| `boost` |
+| `ChargerControl` | boolean |
+| `DefaultChargeMode` | `EnyoChargeModeEnum` |
+| `PriceLimitCtPerKwh` | number, **ct/kWh** (`7` = 7 ct/kWh) |
+| `CostOptimizedTarget` | wall-clock `"07:30"` + IANA timezone |
+
+An energy manager declares what it honours, next to `registerFeatures()`:
+
+```typescript
+em.registerSupportedSettings([
+    EnergyManagerSettingEnum.BatteryControl,
+    EnergyManagerSettingEnum.BatteryChargingMode,
+    EnergyManagerSettingEnum.ChargerControl,
+    EnergyManagerSettingEnum.DefaultChargeMode,
+]);
+
+// seed defaults without ever overriding the user
+await em.setEnergyManagerSettings(
+    { batteryControl: true, batteryChargingMode: EnergyManagerBatteryChargingModeEnum.Paced },
+    { onlyIfUnset: true },
+);
+```
+
+Anyone can read and react:
+
+```typescript
+const state = await em.getEnergyManagerSettings();   // null when no EM is configured
+if (state?.supported.includes(EnergyManagerSettingEnum.ChargerControl)
+    && state.values.chargerControl === false) {
+    skipChargerOptimization();
+}
+
+const id = em.listenForEnergyManagerSettingsChange(async ({ changed, state }) => {
+    if (changed.includes(EnergyManagerSettingEnum.DefaultChargeMode)) {
+        await applyChargeMode(state.values.defaultChargeMode);
+    }
+});
+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.
+- **`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`
 
 Register, retrieve, and manage electricity tariffs. One tariff can be marked as the system default.
@@ -1334,8 +1394,68 @@ Requires the `Savings` permission.
 
 ### Operational Utilities
 
+#### `useOnboardingV2(): EnergyAppOnboardingV2`
+
+Serve the onboarding guides your app ships. Guides are **pulled, not published**: you register one handler, and the host calls it with "give me your v2 onboarding guides". You answer with the **complete set** or with **nothing** — there is no save, update or delete, and every answer replaces the host's picture of what your app offers.
+
+```typescript
+await energyApp.useOnboardingV2().registerOnboardingGuidesHandler(async (request) => {
+    const result = { requestId: request.requestId, guides: buildGuides() };
+
+    const { ok, errors } = validateOnboardingV2GuidesResult(result, {
+        files: packageDefinition.files,
+    });
+    if (!ok) {
+        console.error('onboarding guides invalid', errors);
+        return null;   // keep whatever the host already has
+    }
+
+    return result;
+});
+```
+
+`null` and `[]` are **not** the same answer: `[]` says "I genuinely have no guides" and drops the host's cached ones, `null` says "I cannot answer right now" and leaves them alone. Use `null` for transient failures. The host stops waiting after `request.timeoutMs`, so build the guides in memory rather than fetching them.
+
+Guides declare **slots**, not values: `onboardingV2Block.dynamic(id, kind)` for an OCPP URL or a device IP. Register a second handler to fill them, and return `null` for anything you cannot resolve — a dynamic block is passive content, so an unresolved value never strands a run.
+
+```typescript
+await energyApp.useOnboardingV2().registerDynamicValueHandler(async (request) => {
+    if (request.kind !== EnyoOnboardingV2DynamicKind.OcppUrl) return null;
+
+    const { cloud, local } = await energyApp.useOcpp().getAvailableConnectionDetails();
+    const endpoint = cloud ?? local;
+    if (!endpoint) return null;   // unavailable beats wrong
+
+    return { requestId: request.requestId, kind: request.kind, value: endpoint.url };
+});
+```
+
+Guides can also carry `additional-setup` blocks — the one interactive block **your app** judges. It collects fields (including masked `Password`/`Token` fields, which v2 previously had no way to gather at all), calls a third handler, and branches on the outcome you return:
+
+```typescript
+await energyApp.useOnboardingV2().registerAdditionalSetupHandler(async (request) => {
+    if (request.setupKey !== 'vendor-cloud-token') return { requestId: request.requestId, outcome: 'failed' };
+    const token = request.values.find((v) => v.name === 'api-token')?.value;
+    if (!token || !(await vendorCloud.verify(token))) {
+        return { requestId: request.requestId, outcome: 'invalid' };
+    }
+    await energyApp.useSecretManager().saveSecret('vendor-cloud', { token });
+    return { requestId: request.requestId, outcome: 'connected' };
+});
+```
+
+Every such block must declare a `failed` outcome — it absorbs a rejection, a timeout, a missing handler, and an outcome value matching no branch (guide and handler are linked only by strings). Secrets are never logged, never prefilled, and not kept in run state. See [ONBOARDING.md](./ONBOARDING.md#app-defined-setups-additional-setup).
+
+Your answer wins over the host's own resolution, so a wrong value is worse than none — the installer pastes it into a charger and it fails minutes later as an `ocpp-connect` timeout. `validateOnboardingV2DynamicResult()` catches the copy-target mistakes (whitespace, a non-absolute URL, a plaintext scheme).
+
+Each guide must carry the `vendorId`, `modelIds` and `startVariant` it applies to — that is how the host selects one for a run, and there is no publish step left to bind them. See [ONBOARDING.md](./ONBOARDING.md#serving-guides-the-host-pulls-the-app-never-publishes) for the full v2 model.
+
+Not permission-gated.
+
 #### `useOnboarding(): EnergyAppOnboarding`
 
+> **Deprecated** — the v1 model. New guides use the v2 graph model and are served through [`useOnboardingV2()`](#useonboardingv2-energyapponboardingv2).
+
 Drive a multi-step onboarding guide — start / advance / back / skip / cancel, persist responses, and observe step transitions.
 
 ```typescript

package/dist/cjs/energy-app.cjs

@@ -117,6 +117,20 @@ class EnergyApp {
     useOnboarding() {
         return this.energyAppSdk.useOnboarding();
     }
+    /**
+     * Gets the Onboarding v2 API for serving this app's onboarding guides.
+     *
+     * Guides are pulled rather than published: the app registers one handler and
+     * the host calls it with "give me your v2 onboarding guides", receiving the
+     * complete current set or nothing. There is no save, update or delete —
+     * every answer replaces the host's picture of what this app offers.
+     *
+     * Available to every app — this API is not permission-gated.
+     * @returns The Onboarding v2 API instance
+     */
+    useOnboardingV2() {
+        return this.energyAppSdk.useOnboardingV2();
+    }
     /**
      * Gets the Secret Manager API for retrieving secrets from the developer organization.
      * Provides methods to fetch secrets that have been configured in the developer org's secret store.

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

@@ -16,6 +16,7 @@ import { EnergyAppNotification } from "./packages/energy-app-notification.cjs";
 import { EnergyAppSecretManager } from "./packages/energy-app-secret-manager.cjs";
 import { EnergyAppLocation } from "./packages/energy-app-location.cjs";
 import { EnergyAppOnboarding } from "./packages/energy-app-onboarding.cjs";
+import { EnergyAppOnboardingV2 } from "./packages/energy-app-onboarding-v2.cjs";
 import { EnergyAppTimeseries } from "./packages/energy-app-timeseries.cjs";
 import { EnyoPackageChannel } from "./enyo-package-channel.cjs";
 import { EnergyAppEnergyManager } from "./packages/energy-app-energy-manager.cjs";
@@ -99,6 +100,18 @@ export declare class EnergyApp implements EnyoEnergyAppSdk {
     useElectricityPrices(): EnergyAppEnergyPrices;
     useNotification(): EnergyAppNotification;
     useOnboarding(): EnergyAppOnboarding;
+    /**
+     * Gets the Onboarding v2 API for serving this app's onboarding guides.
+     *
+     * Guides are pulled rather than published: the app registers one handler and
+     * the host calls it with "give me your v2 onboarding guides", receiving the
+     * complete current set or nothing. There is no save, update or delete —
+     * every answer replaces the host's picture of what this app offers.
+     *
+     * Available to every app — this API is not permission-gated.
+     * @returns The Onboarding v2 API instance
+     */
+    useOnboardingV2(): EnergyAppOnboardingV2;
     /**
      * Gets the Secret Manager API for retrieving secrets from the developer organization.
      * Provides methods to fetch secrets that have been configured in the developer org's secret store.

package/dist/cjs/enyo-energy-app-sdk.d.cts

@@ -15,6 +15,7 @@ import { EnergyAppNotification } from "./packages/energy-app-notification.cjs";
 import { EnergyAppSecretManager } from "./packages/energy-app-secret-manager.cjs";
 import { EnergyAppLocation } from "./packages/energy-app-location.cjs";
 import { EnergyAppOnboarding } from "./packages/energy-app-onboarding.cjs";
+import { EnergyAppOnboardingV2 } from "./packages/energy-app-onboarding-v2.cjs";
 import { EnergyAppTimeseries } from "./packages/energy-app-timeseries.cjs";
 import { EnyoPackageChannel } from "./enyo-package-channel.cjs";
 import { EnergyAppEnergyManager } from "./packages/energy-app-energy-manager.cjs";
@@ -106,6 +107,8 @@ export interface EnyoEnergyAppSdk {
     useLocation: () => EnergyAppLocation;
     /** Get the Onboarding API */
     useOnboarding: () => EnergyAppOnboarding;
+    /** Get the Onboarding v2 API for registering the handler the host calls to collect this app's onboarding guides */
+    useOnboardingV2: () => EnergyAppOnboardingV2;
     /** Get the Timeseries API for querying historical energy data */
     useTimeseries: () => EnergyAppTimeseries;
     /** Get the Energy Manager API for retrieving energy manager info and capabilities */

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

@@ -0,0 +1,263 @@
+"use strict";
+/**
+ * Client-side validation for {@link EnergyManagerSettingsState} — the general
+ * settings an energy manager declares and the values stored against them.
+ *
+ * Two classes of problem live here, and only the second is obvious:
+ *
+ * 1. **Malformed values.** A `HH:mm` that is not a time, a timezone that is not
+ *    an IANA zone, a price that is not a finite number. These fail at planning
+ *    time, in the dark, on the night the charge was supposed to happen.
+ * 2. **Values that can never take effect.** A heating-rod mode stored while rod
+ *    control is off, a price limit while the default charge mode is
+ *    cost-optimized. Nothing rejects these — they simply do nothing, which reads
+ *    to a user as "the app ignored me".
+ *
+ * The second class is why {@link ENERGY_MANAGER_SETTING_DEPENDENCIES} exists as
+ * data: the gate tree is checked here rather than restated by every surface.
+ *
+ * `errors` mean the state is malformed; `warnings` are advisory. Use
+ * {@link validateEnergyManagerSettingsState} for the non-throwing result, or
+ * {@link assertValidEnergyManagerSettingsState} to throw.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnergyManagerSettingsValidationError = void 0;
+exports.validateEnergyManagerSettingsState = validateEnergyManagerSettingsState;
+exports.assertValidEnergyManagerSettingsState = assertValidEnergyManagerSettingsState;
+const enyo_energy_manager_settings_js_1 = require("../../types/enyo-energy-manager-settings.cjs");
+const enyo_data_bus_value_js_1 = require("../../types/enyo-data-bus-value.cjs");
+/**
+ * Thrown by {@link assertValidEnergyManagerSettingsState} when a state fails
+ * validation. The message lists every blocking error so callers can surface them
+ * directly.
+ */
+class EnergyManagerSettingsValidationError extends Error {
+    /** The individual blocking errors that caused the failure. */
+    errors;
+    /**
+     * @param errors - The blocking validation errors.
+     */
+    constructor(errors) {
+        super(`Invalid energy manager settings:\n- ${errors.join('\n- ')}`);
+        this.name = 'EnergyManagerSettingsValidationError';
+        this.errors = errors;
+    }
+}
+exports.EnergyManagerSettingsValidationError = EnergyManagerSettingsValidationError;
+/** Every {@link EnergyManagerSettingEnum} value. */
+const SETTINGS = new Set(Object.values(enyo_energy_manager_settings_js_1.EnergyManagerSettingEnum));
+/** 24-hour `HH:mm`, the format {@link EnergyManagerSettingValues.costOptimizedTargetTime} uses. */
+const TIME_RE = /^([01]\d|2[0-3]):[0-5]\d$/;
+/**
+ * Plausible band for a price limit in ct/kWh.
+ *
+ * Wide on purpose, and negative at the bottom: wholesale prices go negative, and
+ * "charge only when I am paid to" is a real preference. The band exists to catch
+ * a EUR/kWh value entered into a ct/kWh field (`0.07` where `7` was meant) and
+ * the reverse (`700`), not to express an opinion about tariffs.
+ */
+const PRICE_LIMIT_MIN_CT = -100;
+const PRICE_LIMIT_MAX_CT = 200;
+/**
+ * Below this, a {@link EnergyManagerSettingValues.batteryDischargeWhileChargingWh}
+ * 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.
+ */
+const DISCHARGE_BUDGET_MIN_PLAUSIBLE_WH = 100;
+/** 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));
+const CHARGE_MODES = new Set(Object.values(enyo_data_bus_value_js_1.EnyoChargeModeEnum));
+/**
+ * True when `timezone` is an IANA zone this runtime recognises.
+ *
+ * Uses `Intl` rather than a pattern: `"Europe/Berlin"` and `"Europe/Berln"` are
+ * indistinguishable by shape, and only the first one resolves a wall-clock time.
+ *
+ * @param timezone - The candidate IANA timezone identifier.
+ * @returns True when the runtime accepts it.
+ */
+function isValidTimezone(timezone) {
+    try {
+        new Intl.DateTimeFormat('en-US', { timeZone: timezone });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Reads the effective value a dependency is gated on.
+ *
+ * @param values - The stored values.
+ * @param setting - The gating setting.
+ * @returns The gate's current value, or `undefined` when it is unset.
+ */
+function gateValue(values, setting) {
+    const [key] = enyo_energy_manager_settings_js_1.ENERGY_MANAGER_SETTING_VALUE_KEYS[setting];
+    return key ? values[key] : undefined;
+}
+/**
+ * Validates an energy manager settings state: the declared support list, the
+ * value formats, and the gate tree between them.
+ *
+ * Checks applied:
+ *
+ * - `supported` holds only {@link EnergyManagerSettingEnum} members, without
+ *   duplicates (**error**).
+ * - Each stored value has the right type, and each enum-valued setting holds an
+ *   enum member (**error**).
+ * - `costOptimizedTargetTime` is `HH:mm`, and `costOptimizedTimezone` is an IANA
+ *   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).
+ * - 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
+ *   effect; see {@link ENERGY_MANAGER_SETTING_DEPENDENCIES}).
+ * - A supported gate whose dependants are unsupported (**warning** — a
+ *   half-built control surface).
+ * - `costOptimizedTargetTime` set without a timezone (**warning** — the
+ *   wall-clock value is ambiguous across a DST boundary).
+ *
+ * @param state - The settings state to validate.
+ * @returns The {@link EnergyManagerSettingsValidationResult}.
+ *
+ * @example
+ * ```typescript
+ * const {ok, errors, warnings} = validateEnergyManagerSettingsState(state);
+ * warnings.forEach((w) => console.warn('energy manager settings:', w));
+ * if (!ok) console.error('energy manager settings are malformed', errors);
+ * ```
+ */
+function validateEnergyManagerSettingsState(state) {
+    const errors = [];
+    const warnings = [];
+    if (!state)
+        return { ok: false, errors: ['state is required.'], warnings };
+    if (!Array.isArray(state.supported)) {
+        return { ok: false, errors: ['`supported` must be an array.'], warnings };
+    }
+    const supported = new Set();
+    for (const setting of state.supported) {
+        if (!SETTINGS.has(setting)) {
+            errors.push(`\`supported\` contains "${setting}", which is not an EnergyManagerSettingEnum member.`);
+        }
+        else if (supported.has(setting)) {
+            errors.push(`\`supported\` lists "${setting}" more than once.`);
+        }
+        else {
+            supported.add(setting);
+        }
+    }
+    const values = state.values ?? {};
+    // ── value formats ──────────────────────────────────────────────────────
+    for (const key of ['batteryControl', 'batteryChargeFromGrid',
+        'blockBatteryDischargeWhileEvDischarging', 'heatpumpControl',
+        'heatingRodControl', 'chargerControl']) {
+        if (values[key] !== undefined && typeof values[key] !== 'boolean') {
+            errors.push(`\`${key}\` must be a boolean when set.`);
+        }
+    }
+    if (values.batteryChargingMode !== undefined
+        && !BATTERY_CHARGING_MODES.has(values.batteryChargingMode)) {
+        errors.push(`\`batteryChargingMode\` "${values.batteryChargingMode}" is not an EnergyManagerBatteryChargingModeEnum member.`);
+    }
+    if (values.heatingRodMode !== undefined && !HEATING_ROD_MODES.has(values.heatingRodMode)) {
+        errors.push(`\`heatingRodMode\` "${values.heatingRodMode}" is not an EnergyManagerHeatingRodModeEnum member.`);
+    }
+    if (values.defaultChargeMode !== undefined && !CHARGE_MODES.has(values.defaultChargeMode)) {
+        errors.push(`\`defaultChargeMode\` "${values.defaultChargeMode}" is not an EnyoChargeModeEnum member.`);
+    }
+    if (values.priceLimitCtPerKwh !== undefined) {
+        if (typeof values.priceLimitCtPerKwh !== 'number'
+            || !Number.isFinite(values.priceLimitCtPerKwh)) {
+            errors.push('`priceLimitCtPerKwh` must be a finite number when set.');
+        }
+        else if (values.priceLimitCtPerKwh < PRICE_LIMIT_MIN_CT
+            || values.priceLimitCtPerKwh > PRICE_LIMIT_MAX_CT) {
+            warnings.push(`\`priceLimitCtPerKwh\` is ${values.priceLimitCtPerKwh}, outside the plausible ` +
+                `${PRICE_LIMIT_MIN_CT}…${PRICE_LIMIT_MAX_CT} ct/kWh band — this field is in ` +
+                'cents per kWh, not EUR per kWh.');
+        }
+    }
+    if (values.batteryDischargeWhileChargingWh !== undefined
+        && values.batteryDischargeWhileChargingWh !== null) {
+        const budget = values.batteryDischargeWhileChargingWh;
+        if (typeof budget !== 'number' || !Number.isFinite(budget)) {
+            errors.push('`batteryDischargeWhileChargingWh` must be a finite number or `null` when set.');
+        }
+        else if (budget < 0) {
+            errors.push(`\`batteryDischargeWhileChargingWh\` is ${budget}; a discharge budget cannot be ` +
+                'negative. Use `null` to disable the transfer entirely.');
+        }
+        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.');
+        }
+    }
+    if (values.costOptimizedTargetTime !== undefined) {
+        if (typeof values.costOptimizedTargetTime !== 'string'
+            || !TIME_RE.test(values.costOptimizedTargetTime)) {
+            errors.push(`\`costOptimizedTargetTime\` "${values.costOptimizedTargetTime}" is not a 24-hour HH:mm time.`);
+        }
+        if (values.costOptimizedTimezone === undefined) {
+            warnings.push('`costOptimizedTargetTime` is set without `costOptimizedTimezone` — the wall-clock ' +
+                'value cannot be resolved unambiguously across a DST boundary.');
+        }
+    }
+    if (values.costOptimizedTimezone !== undefined) {
+        if (typeof values.costOptimizedTimezone !== 'string'
+            || !isValidTimezone(values.costOptimizedTimezone)) {
+            errors.push(`\`costOptimizedTimezone\` "${values.costOptimizedTimezone}" is not an IANA timezone.`);
+        }
+    }
+    // ── 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);
+        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.');
+        }
+    }
+    // ── gate tree ──────────────────────────────────────────────────────────
+    for (const [setting, dependency] of Object.entries(enyo_energy_manager_settings_js_1.ENERGY_MANAGER_SETTING_DEPENDENCIES)) {
+        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);
+        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.`);
+        }
+        if (supported.has(dependency.requires) && !supported.has(key)
+            && gateValue(values, dependency.requires) === dependency.equals) {
+            warnings.push(`"${dependency.requires}" is supported and active, but its dependent setting ` +
+                `"${key}" is not — the user is offered a gate with nothing behind it.`);
+        }
+    }
+    return { ok: errors.length === 0, errors, warnings };
+}
+/**
+ * Like {@link validateEnergyManagerSettingsState}, but throws
+ * {@link EnergyManagerSettingsValidationError} when there are blocking errors.
+ * Warnings never throw; the validated state is returned on success for chaining.
+ *
+ * @param state - The settings state to validate.
+ * @returns The same state when it has no blocking errors.
+ * @throws {EnergyManagerSettingsValidationError} When validation produces any error.
+ */
+function assertValidEnergyManagerSettingsState(state) {
+    const { ok, errors } = validateEnergyManagerSettingsState(state);
+    if (!ok)
+        throw new EnergyManagerSettingsValidationError(errors);
+    return state;
+}

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

@@ -0,0 +1,91 @@
+/**
+ * Client-side validation for {@link EnergyManagerSettingsState} — the general
+ * settings an energy manager declares and the values stored against them.
+ *
+ * Two classes of problem live here, and only the second is obvious:
+ *
+ * 1. **Malformed values.** A `HH:mm` that is not a time, a timezone that is not
+ *    an IANA zone, a price that is not a finite number. These fail at planning
+ *    time, in the dark, on the night the charge was supposed to happen.
+ * 2. **Values that can never take effect.** A heating-rod mode stored while rod
+ *    control is off, a price limit while the default charge mode is
+ *    cost-optimized. Nothing rejects these — they simply do nothing, which reads
+ *    to a user as "the app ignored me".
+ *
+ * The second class is why {@link ENERGY_MANAGER_SETTING_DEPENDENCIES} exists as
+ * data: the gate tree is checked here rather than restated by every surface.
+ *
+ * `errors` mean the state is malformed; `warnings` are advisory. Use
+ * {@link validateEnergyManagerSettingsState} for the non-throwing result, or
+ * {@link assertValidEnergyManagerSettingsState} to throw.
+ */
+import type { EnergyManagerSettingsState } from '../../types/enyo-energy-manager-settings.cjs';
+/**
+ * Thrown by {@link assertValidEnergyManagerSettingsState} when a state fails
+ * validation. The message lists every blocking error so callers can surface them
+ * directly.
+ */
+export declare class EnergyManagerSettingsValidationError extends Error {
+    /** The individual blocking errors that caused the failure. */
+    readonly errors: string[];
+    /**
+     * @param errors - The blocking validation errors.
+     */
+    constructor(errors: string[]);
+}
+/** The outcome of validating an {@link EnergyManagerSettingsState}. */
+export interface EnergyManagerSettingsValidationResult {
+    /** True when there are no blocking `errors` (warnings are still allowed). */
+    ok: boolean;
+    /** Blocking problems — the state is malformed. */
+    errors: string[];
+    /** Advisory problems — allowed, but usually worth fixing. */
+    warnings: string[];
+}
+/**
+ * Validates an energy manager settings state: the declared support list, the
+ * value formats, and the gate tree between them.
+ *
+ * Checks applied:
+ *
+ * - `supported` holds only {@link EnergyManagerSettingEnum} members, without
+ *   duplicates (**error**).
+ * - Each stored value has the right type, and each enum-valued setting holds an
+ *   enum member (**error**).
+ * - `costOptimizedTargetTime` is `HH:mm`, and `costOptimizedTimezone` is an IANA
+ *   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).
+ * - 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
+ *   effect; see {@link ENERGY_MANAGER_SETTING_DEPENDENCIES}).
+ * - A supported gate whose dependants are unsupported (**warning** — a
+ *   half-built control surface).
+ * - `costOptimizedTargetTime` set without a timezone (**warning** — the
+ *   wall-clock value is ambiguous across a DST boundary).
+ *
+ * @param state - The settings state to validate.
+ * @returns The {@link EnergyManagerSettingsValidationResult}.
+ *
+ * @example
+ * ```typescript
+ * const {ok, errors, warnings} = validateEnergyManagerSettingsState(state);
+ * warnings.forEach((w) => console.warn('energy manager settings:', w));
+ * if (!ok) console.error('energy manager settings are malformed', errors);
+ * ```
+ */
+export declare function validateEnergyManagerSettingsState(state: EnergyManagerSettingsState): EnergyManagerSettingsValidationResult;
+/**
+ * Like {@link validateEnergyManagerSettingsState}, but throws
+ * {@link EnergyManagerSettingsValidationError} when there are blocking errors.
+ * Warnings never throw; the validated state is returned on success for chaining.
+ *
+ * @param state - The settings state to validate.
+ * @returns The same state when it has no blocking errors.
+ * @throws {EnergyManagerSettingsValidationError} When validation produces any error.
+ */
+export declare function assertValidEnergyManagerSettingsState(state: EnergyManagerSettingsState): EnergyManagerSettingsState;