hoffmation-base 3.7.3 → 4.0.0

package/lib/utils/energy-manager-utils.d.ts

@@ -1,6 +1,128 @@
-import { iExcessEnergyConsumer } from '../interfaces';
+import { iEnergyHistoryOutlook, iEnergyManager, iExcessEnergyConsumer, iMorningReserveVerdict } from '../interfaces';
 import { EnergyConsumerStateChange } from './energy-consumer-state-change';
 export declare class EnergyManagerUtils {
+    /**
+     * The plant's single reading of its recorded history, and the single record of what the model rung would
+     * have decided.
+     *
+     * Static, the way {@link Devices.energymanager} is a single place: there is one energy manager, so there is
+     * one history and one shadow. Two of either would mean the paid backfill twice a day and, after a week, two
+     * half samples of a measurement that only means anything whole.
+     *
+     * Held here rather than on a manager so that **every** manager can carry
+     * {@link iEnergyManager.morningOutlook} by delegating instead of copying - see
+     * {@link EnergyManagerUtils.turnOnAdditionalConsumer}, which is shared for the same reason.
+     */
+    private static _energyHistory;
+    private static _modelShadow;
+    /**
+     * Which manager the two above were built for. A different manager is a different plant reading, and
+     * carrying the old cache over would answer about the previous manager's battery.
+     */
+    private static _historyOwner;
+    /**
+     * Brings the plant's recorded history up to date, as far as anything has gone stale.
+     *
+     * Meant to be called from the manager's own loop, however fast that runs: each of the reads behind it
+     * throttles itself, so calling it every five seconds costs the same number of queries as calling it once an
+     * hour. A manager that states no dials reads nothing at all and pays no request quota.
+     * @param manager - The plant's energy manager.
+     */
+    static refreshEnergyHistory(manager: iEnergyManager): void;
+    /**
+     * What the plant's recorded history says about the coming morning low - the shared implementation of
+     * {@link iEnergyManager.morningOutlook}, so no manager has to write one of its own.
+     *
+     * **The one place the marker for "no charge level" is told from a charge level.** Run through the
+     * projection the marker moves the whole band, and on a clear morning that band still clears the reserve, so
+     * a consumer would be answered at exactly the charge level at which it must not be. A manager without a
+     * battery at all lands in the same branch, and rightly: neither offers a starting point for a projection.
+     *
+     * Pure arithmetic over what {@link refreshEnergyHistory} has already read, so a consumer may ask on every
+     * one of its own decisions without costing a query.
+     * @param manager - The plant's energy manager.
+     * @returns The outlook, or undefined while this manager can say nothing about the coming morning.
+     */
+    static morningOutlook(manager: iEnergyManager): iEnergyHistoryOutlook | undefined;
+    /**
+     * Whether the plant expects the coming morning to hold its reserve - the shared implementation of
+     * {@link iEnergyManager.morningReserveVerdict}.
+     *
+     * Four rungs, in the order they have to be checked in: the model free bound holds the reserve, the bound
+     * misses it and no sun is left to change that, the fitted band falls entirely on one side of the reserve,
+     * and no statement. A bound below the reserve while sun is still left is deliberately **not** a "misses":
+     * the yield of the remaining day can still carry the morning, and only the model can say whether it will.
+     *
+     * The first two rungs are arithmetic on the plant's own measured consumption and carry no unmeasured
+     * assumption, which is what {@link iMorningReserveVerdict.measured} marks them by. The third rests on a fit
+     * whose window length has never been checked against recorded data - it is reported so an operator can read
+     * what the model would have said, and consumers that move something leave it alone.
+     * @param manager - The plant's energy manager, whose settings state the two thresholds.
+     * @param outlook - What the plant said, or undefined while it can say nothing. Handed in rather than read
+     * again, so a caller that already read it judges the same moment it read.
+     * @returns The verdict, or undefined while there is no outlook or the manager states no thresholds to judge
+     * by - a verdict against a guessed reserve would read exactly like one against a stated reserve.
+     */
+    static morningReserveVerdict(manager: iEnergyManager, outlook: iEnergyHistoryOutlook | undefined): iMorningReserveVerdict | undefined;
+    /**
+     * Assembles one verdict out of the rung that reached it and the numbers it was reached on.
+     * @param outlook - What the plant said.
+     * @param reserve - The reserve in percent the rung measured against.
+     * @param holds - Whether the coming morning holds, misses, or cannot be judged.
+     * @param measured - Whether the rung needed no fitted model.
+     * @param band - The projected morning charge level at both edges, collapsed where no band was needed.
+     * @param reason - What made this rung answer.
+     * @returns The verdict.
+     */
+    private static verdict;
+    /**
+     * How the model free bound reads in a reason line - either its value or why there is none.
+     *
+     * The three ways it can be absent look alike from the outside and must not: an operator who reads "no
+     * consumption history" while the history is there looks in the wrong place.
+     * @param outlook - What the plant said.
+     * @returns The text to put into the reason.
+     */
+    private static boundText;
+    /**
+     * Why there is no band. Which of the three causes is named decides where the operator looks, and from the
+     * outside they look alike.
+     * @param outlook - What the plant said.
+     * @returns The text to put into the reason.
+     */
+    private static missingModelText;
+    /**
+     * Records what the rung that rests on the fitted model would have decided, without letting it move
+     * anything.
+     *
+     * The rung rests on a fit whose window length has never been measured against recorded data, and on
+     * synthetic data the delivered length scores worse than the trivial rule the line quotes. Reading a week of
+     * these lines is what turns that open question into a measurement - see {@link ModelShadow}.
+     *
+     * Measured against the plant's single reserve, so a week of lines is one sample: two tallies against two
+     * thresholds cannot be added.
+     * @param manager - The plant's energy manager.
+     * @param outlook - What the plant said, or undefined while it can say nothing.
+     * @param alreadyDecided - Whether a rung that needs no model already answered this situation. The model
+     * rung sits below such a rung, so a verdict taken where the other one decides is not a verdict this rung
+     * ever reaches in operation.
+     */
+    static observeModelShadow(manager: iEnergyManager, outlook: iEnergyHistoryOutlook | undefined, alreadyDecided: boolean): void;
+    /**
+     * The plant's history, built on first use and rebuilt when the manager it belongs to changes.
+     * @param manager - The plant's energy manager.
+     * @returns The service, or undefined while this manager states no dials to read a history with.
+     */
+    private static energyHistory;
+    /**
+     * A live view of the dials the history is read and fitted with.
+     *
+     * Getters rather than a snapshot: all three are editable at runtime, and a service holding the values of the
+     * moment of construction would answer on a window nobody configured any more.
+     * @param manager - The plant's energy manager.
+     * @returns The options, or undefined while the manager states none of them.
+     */
+    private static energyHistoryOptions;
     static turnOnAdditionalConsumer(excessEnergyConsumer: iExcessEnergyConsumer[], lastDeviceChange: EnergyConsumerStateChange | undefined): void | undefined | EnergyConsumerStateChange;
     static turnOffAdditionalConsumer(excessEnergyConsumer: iExcessEnergyConsumer[], lastDeviceChange: EnergyConsumerStateChange | undefined): void | undefined | EnergyConsumerStateChange;
 }

package/lib/utils/energy-manager-utils.js

@@ -2,7 +2,233 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EnergyManagerUtils = void 0;
 const enums_1 = require("../enums");
+const services_1 = require("../services");
+const model_shadow_1 = require("./model-shadow");
+const utils_1 = require("./utils");
+/**
+ * The subject the plant's shadow line names itself by. Deliberately not a manager's name: the record belongs
+ * to the plant, and whichever manager it happens to run under, an operator reads one line about one sample.
+ */
+const MODEL_SHADOW_SUBJECT = 'energy manager model rung';
 class EnergyManagerUtils {
+    /**
+     * Brings the plant's recorded history up to date, as far as anything has gone stale.
+     *
+     * Meant to be called from the manager's own loop, however fast that runs: each of the reads behind it
+     * throttles itself, so calling it every five seconds costs the same number of queries as calling it once an
+     * hour. A manager that states no dials reads nothing at all and pays no request quota.
+     * @param manager - The plant's energy manager.
+     */
+    static refreshEnergyHistory(manager) {
+        var _a;
+        (_a = EnergyManagerUtils.energyHistory(manager)) === null || _a === void 0 ? void 0 : _a.refresh();
+    }
+    /**
+     * What the plant's recorded history says about the coming morning low - the shared implementation of
+     * {@link iEnergyManager.morningOutlook}, so no manager has to write one of its own.
+     *
+     * **The one place the marker for "no charge level" is told from a charge level.** Run through the
+     * projection the marker moves the whole band, and on a clear morning that band still clears the reserve, so
+     * a consumer would be answered at exactly the charge level at which it must not be. A manager without a
+     * battery at all lands in the same branch, and rightly: neither offers a starting point for a projection.
+     *
+     * Pure arithmetic over what {@link refreshEnergyHistory} has already read, so a consumer may ask on every
+     * one of its own decisions without costing a query.
+     * @param manager - The plant's energy manager.
+     * @returns The outlook, or undefined while this manager can say nothing about the coming morning.
+     */
+    static morningOutlook(manager) {
+        var _a;
+        const currentSoc = manager.batteryLevel;
+        if (currentSoc === undefined || currentSoc < 0) {
+            return undefined;
+        }
+        return (_a = EnergyManagerUtils.energyHistory(manager)) === null || _a === void 0 ? void 0 : _a.outlook(currentSoc, new Date());
+    }
+    /**
+     * Whether the plant expects the coming morning to hold its reserve - the shared implementation of
+     * {@link iEnergyManager.morningReserveVerdict}.
+     *
+     * Four rungs, in the order they have to be checked in: the model free bound holds the reserve, the bound
+     * misses it and no sun is left to change that, the fitted band falls entirely on one side of the reserve,
+     * and no statement. A bound below the reserve while sun is still left is deliberately **not** a "misses":
+     * the yield of the remaining day can still carry the morning, and only the model can say whether it will.
+     *
+     * The first two rungs are arithmetic on the plant's own measured consumption and carry no unmeasured
+     * assumption, which is what {@link iMorningReserveVerdict.measured} marks them by. The third rests on a fit
+     * whose window length has never been checked against recorded data - it is reported so an operator can read
+     * what the model would have said, and consumers that move something leave it alone.
+     * @param manager - The plant's energy manager, whose settings state the two thresholds.
+     * @param outlook - What the plant said, or undefined while it can say nothing. Handed in rather than read
+     * again, so a caller that already read it judges the same moment it read.
+     * @returns The verdict, or undefined while there is no outlook or the manager states no thresholds to judge
+     * by - a verdict against a guessed reserve would read exactly like one against a stated reserve.
+     */
+    static morningReserveVerdict(manager, outlook) {
+        if (outlook === undefined) {
+            return undefined;
+        }
+        const dials = manager.settings;
+        const reserve = dials.minimumMorningSocReserve;
+        const noSunThresholdHours = dials.noSunThresholdHours;
+        if (reserve === undefined || noSunThresholdHours === undefined) {
+            return undefined;
+        }
+        const collapsed = { lower: outlook.currentSoc, upper: outlook.currentSoc };
+        const boundText = EnergyManagerUtils.boundText(outlook);
+        const worstCaseLowSoc = outlook.worstCaseLowSoc;
+        if (worstCaseLowSoc !== undefined) {
+            if (worstCaseLowSoc >= reserve) {
+                return EnergyManagerUtils.verdict(outlook, reserve, true, true, collapsed, `${boundText} holds the reserve without a model`);
+            }
+            if (outlook.remainingSunHours < noSunThresholdHours) {
+                return EnergyManagerUtils.verdict(outlook, reserve, false, true, collapsed, `${boundText} misses the reserve and only ${utils_1.Utils.round(outlook.remainingSunHours, 2)}h of sun are left`);
+            }
+        }
+        const band = outlook.band;
+        if (band === undefined) {
+            return EnergyManagerUtils.verdict(outlook, reserve, undefined, false, collapsed, `no statement; ${EnergyManagerUtils.missingModelText(outlook)}; ${boundText}, ` +
+                `${utils_1.Utils.round(outlook.remainingSunHours, 2)}h of sun left`);
+        }
+        if (band.lower >= reserve) {
+            return EnergyManagerUtils.verdict(outlook, reserve, true, false, band, 'the lower band edge holds the reserve');
+        }
+        if (band.upper < reserve) {
+            return EnergyManagerUtils.verdict(outlook, reserve, false, false, band, 'the upper band edge misses the reserve');
+        }
+        return EnergyManagerUtils.verdict(outlook, reserve, undefined, false, band, `the reserve lies inside the band; ${boundText}`);
+    }
+    /**
+     * Assembles one verdict out of the rung that reached it and the numbers it was reached on.
+     * @param outlook - What the plant said.
+     * @param reserve - The reserve in percent the rung measured against.
+     * @param holds - Whether the coming morning holds, misses, or cannot be judged.
+     * @param measured - Whether the rung needed no fitted model.
+     * @param band - The projected morning charge level at both edges, collapsed where no band was needed.
+     * @param reason - What made this rung answer.
+     * @returns The verdict.
+     */
+    static verdict(outlook, reserve, holds, measured, band, reason) {
+        return {
+            holds,
+            measured,
+            modelFitted: outlook.basis.modelFitted,
+            reason,
+            currentSoc: outlook.currentSoc,
+            band,
+            reserve,
+            sampleDays: outlook.sampleDays,
+        };
+    }
+    /**
+     * How the model free bound reads in a reason line - either its value or why there is none.
+     *
+     * The three ways it can be absent look alike from the outside and must not: an operator who reads "no
+     * consumption history" while the history is there looks in the wrong place.
+     * @param outlook - What the plant said.
+     * @returns The text to put into the reason.
+     */
+    static boundText(outlook) {
+        if (outlook.worstCaseLowSoc !== undefined) {
+            return `worst case low ${utils_1.Utils.round(outlook.worstCaseLowSoc, 2)}%`;
+        }
+        if (!outlook.basis.batteryCapacityKnown) {
+            return 'no battery capacity reported';
+        }
+        if (outlook.basis.consumptionWindows === 0) {
+            return outlook.basis.consumptionReadingsSeen ? 'no usable consumption window' : 'no consumption history';
+        }
+        return (`only ${outlook.basis.consumptionWindows} of ${outlook.basis.requiredConsumptionWindows} ` +
+            'required consumption windows');
+    }
+    /**
+     * Why there is no band. Which of the three causes is named decides where the operator looks, and from the
+     * outside they look alike.
+     * @param outlook - What the plant said.
+     * @returns The text to put into the reason.
+     */
+    static missingModelText(outlook) {
+        if (!outlook.basis.weatherTodayKnown) {
+            return 'no weather aggregate for the running day';
+        }
+        return outlook.basis.consumptionTodayKnown ? 'no fitted model' : 'no consumption reading for the running day';
+    }
+    /**
+     * Records what the rung that rests on the fitted model would have decided, without letting it move
+     * anything.
+     *
+     * The rung rests on a fit whose window length has never been measured against recorded data, and on
+     * synthetic data the delivered length scores worse than the trivial rule the line quotes. Reading a week of
+     * these lines is what turns that open question into a measurement - see {@link ModelShadow}.
+     *
+     * Measured against the plant's single reserve, so a week of lines is one sample: two tallies against two
+     * thresholds cannot be added.
+     * @param manager - The plant's energy manager.
+     * @param outlook - What the plant said, or undefined while it can say nothing.
+     * @param alreadyDecided - Whether a rung that needs no model already answered this situation. The model
+     * rung sits below such a rung, so a verdict taken where the other one decides is not a verdict this rung
+     * ever reaches in operation.
+     */
+    static observeModelShadow(manager, outlook, alreadyDecided) {
+        if (alreadyDecided || (outlook === null || outlook === void 0 ? void 0 : outlook.band) === undefined) {
+            return;
+        }
+        const dials = manager.settings;
+        const reserve = dials.minimumMorningSocReserve;
+        const shadow = EnergyManagerUtils._modelShadow;
+        if (reserve === undefined || shadow === undefined) {
+            // No yardstick is no measurement. Nothing is invented in its place: a rate against a guessed threshold
+            // would look exactly like a rate against a stated one.
+            return;
+        }
+        shadow.observe(outlook.band.lower >= reserve ? 'holds' : 'misses', outlook.currentSoc, `lower band edge ${utils_1.Utils.round(outlook.band.lower, 2)}% against reserve ${reserve}% ` +
+            `(soc ${utils_1.Utils.round(outlook.currentSoc, 2)}%, ${outlook.sampleDays} days)`);
+    }
+    /**
+     * The plant's history, built on first use and rebuilt when the manager it belongs to changes.
+     * @param manager - The plant's energy manager.
+     * @returns The service, or undefined while this manager states no dials to read a history with.
+     */
+    static energyHistory(manager) {
+        if (EnergyManagerUtils._historyOwner === manager) {
+            return EnergyManagerUtils._energyHistory;
+        }
+        const options = EnergyManagerUtils.energyHistoryOptions(manager);
+        EnergyManagerUtils._historyOwner = manager;
+        EnergyManagerUtils._energyHistory =
+            options === undefined ? undefined : new services_1.EnergyHistoryService(options, manager.log.bind(manager));
+        EnergyManagerUtils._modelShadow =
+            options === undefined ? undefined : new model_shadow_1.ModelShadow(MODEL_SHADOW_SUBJECT, manager.log.bind(manager));
+        return EnergyManagerUtils._energyHistory;
+    }
+    /**
+     * A live view of the dials the history is read and fitted with.
+     *
+     * Getters rather than a snapshot: all three are editable at runtime, and a service holding the values of the
+     * moment of construction would answer on a window nobody configured any more.
+     * @param manager - The plant's energy manager.
+     * @returns The options, or undefined while the manager states none of them.
+     */
+    static energyHistoryOptions(manager) {
+        const dials = manager.settings;
+        if ((dials === null || dials === void 0 ? void 0 : dials.historyWindowDays) === undefined ||
+            dials.historyMinimumDays === undefined ||
+            dials.historyBandSigma === undefined) {
+            return undefined;
+        }
+        const stated = dials;
+        return {
+            get windowDays() {
+                return stated.historyWindowDays;
+            },
+            get minimumModelDays() {
+                return stated.historyMinimumDays;
+            },
+            get bandSigma() {
+                return stated.historyBandSigma;
+            },
+        };
+    }
     static turnOnAdditionalConsumer(excessEnergyConsumer, lastDeviceChange) {
         const potentialDevices = excessEnergyConsumer.filter((e) => {
             if (e.energySettings.priority === -1 || e.on || !e.isAvailableForExcessEnergy()) {

package/lib/utils/index.d.ts

@@ -1,6 +1,10 @@
 export * from './catchEmResult';
 export * from './RGB';
+export * from './dayMs';
 export * from './utils';
 export * from './ringStorage';
 export * from './energy-manager-utils';
+export * from './energy-history-utils';
+export * from './model-shadow';
+export * from './morning-verdict';
 export * from './energy-consumer-state-change';

package/lib/utils/index.js

@@ -16,7 +16,11 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./catchEmResult"), exports);
 __exportStar(require("./RGB"), exports);
+__exportStar(require("./dayMs"), exports);
 __exportStar(require("./utils"), exports);
 __exportStar(require("./ringStorage"), exports);
 __exportStar(require("./energy-manager-utils"), exports);
+__exportStar(require("./energy-history-utils"), exports);
+__exportStar(require("./model-shadow"), exports);
+__exportStar(require("./morning-verdict"), exports);
 __exportStar(require("./energy-consumer-state-change"), exports);

package/lib/utils/model-shadow.d.ts

@@ -0,0 +1,61 @@
+import { LogLevel } from '../enums';
+import { MorningVerdict } from './morning-verdict';
+/**
+ * Runs a decision stage alongside the stage that actually decides, and records what it would have decided.
+ *
+ * **Why a stage runs here instead of being switched on.** The length of the fitting window has never been
+ * measured against recorded data, and on synthetic data the delivered length scores worse than
+ * {@link ModelShadow.trivialSuppressSoc} - a single comparison against the state of charge. A stage that may
+ * be worse than that comparison must not move an actuator, and one that is better cannot be recognised as
+ * better without the comparison being made. After a week of operation the log holds enough lines to read the
+ * agreement rate off this plant's real days, which is what turns the open question into a measurement.
+ *
+ * **One per plant.** The measurement is a count of agreements over a week, so a second shadow beside the first
+ * halves the evidence rather than doubling it - and against a second yardstick the two rates cannot even be
+ * added. The energy manager holds the plant's one shadow and measures against the plant's one reserve.
+ */
+export declare class ModelShadow {
+    private readonly subject;
+    private readonly log;
+    /**
+     * The state of charge in percent at or above which the trivial rule calls the coming morning safe.
+     *
+     * Deliberately not a setting. It is the yardstick the model is measured against, and a yardstick an
+     * installation can turn measures nothing: two plants would report agreement rates that cannot be compared,
+     * and a rate could be improved by moving the yardstick rather than the model.
+     */
+    static readonly trivialSuppressSoc: number;
+    private _agreements;
+    private _divergences;
+    /**
+     * The last pairing of the two verdicts, which is what the line is throttled on - not the line itself. The
+     * line carries the running tally and would therefore differ on every single evaluation.
+     */
+    private _lastPairing;
+    /**
+     * Builds a shadow for one stage. It holds no timer and reaches for nothing - it is only written to.
+     * @param subject - What the line names the observing stage by, so the operator sees which stage was read.
+     * @param log - Where the line goes; the device's own logger, so the line carries the device.
+     */
+    constructor(subject: string, log: (level: LogLevel, message: string) => void);
+    /**
+     * How often the model stage and the trivial rule reached the same verdict so far.
+     * @returns The count since this process started.
+     */
+    get agreements(): number;
+    /**
+     * How often the model stage and the trivial rule parted so far.
+     * @returns The count since this process started.
+     */
+    get divergences(): number;
+    /**
+     * Records one verdict of the model stage against what the trivial rule would have said, and reports it
+     * whenever the pairing of the two changed - the loops this sits in run every few seconds, and a line per
+     * pass would bury the change nobody must miss. The running tally rides along on every line, so the newest
+     * line alone answers the whole week.
+     * @param verdict - What the model stage says about the coming morning.
+     * @param currentSoc - The state of charge in percent the trivial rule is evaluated on.
+     * @param detail - The numbers the model stage reached its verdict on, for the operator.
+     */
+    observe(verdict: MorningVerdict, currentSoc: number, detail: string): void;
+}

package/lib/utils/model-shadow.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ModelShadow = void 0;
+const enums_1 = require("../enums");
+const utils_1 = require("./utils");
+/**
+ * Runs a decision stage alongside the stage that actually decides, and records what it would have decided.
+ *
+ * **Why a stage runs here instead of being switched on.** The length of the fitting window has never been
+ * measured against recorded data, and on synthetic data the delivered length scores worse than
+ * {@link ModelShadow.trivialSuppressSoc} - a single comparison against the state of charge. A stage that may
+ * be worse than that comparison must not move an actuator, and one that is better cannot be recognised as
+ * better without the comparison being made. After a week of operation the log holds enough lines to read the
+ * agreement rate off this plant's real days, which is what turns the open question into a measurement.
+ *
+ * **One per plant.** The measurement is a count of agreements over a week, so a second shadow beside the first
+ * halves the evidence rather than doubling it - and against a second yardstick the two rates cannot even be
+ * added. The energy manager holds the plant's one shadow and measures against the plant's one reserve.
+ */
+class ModelShadow {
+    /**
+     * Builds a shadow for one stage. It holds no timer and reaches for nothing - it is only written to.
+     * @param subject - What the line names the observing stage by, so the operator sees which stage was read.
+     * @param log - Where the line goes; the device's own logger, so the line carries the device.
+     */
+    constructor(subject, log) {
+        this.subject = subject;
+        this.log = log;
+        this._agreements = 0;
+        this._divergences = 0;
+    }
+    /**
+     * How often the model stage and the trivial rule reached the same verdict so far.
+     * @returns The count since this process started.
+     */
+    get agreements() {
+        return this._agreements;
+    }
+    /**
+     * How often the model stage and the trivial rule parted so far.
+     * @returns The count since this process started.
+     */
+    get divergences() {
+        return this._divergences;
+    }
+    /**
+     * Records one verdict of the model stage against what the trivial rule would have said, and reports it
+     * whenever the pairing of the two changed - the loops this sits in run every few seconds, and a line per
+     * pass would bury the change nobody must miss. The running tally rides along on every line, so the newest
+     * line alone answers the whole week.
+     * @param verdict - What the model stage says about the coming morning.
+     * @param currentSoc - The state of charge in percent the trivial rule is evaluated on.
+     * @param detail - The numbers the model stage reached its verdict on, for the operator.
+     */
+    observe(verdict, currentSoc, detail) {
+        const trivial = currentSoc >= ModelShadow.trivialSuppressSoc ? 'holds' : 'misses';
+        const agreed = trivial === verdict;
+        if (agreed) {
+            this._agreements++;
+        }
+        else {
+            this._divergences++;
+        }
+        const pairing = `${verdict}/${trivial}`;
+        if (pairing === this._lastPairing) {
+            return;
+        }
+        this._lastPairing = pairing;
+        this.log(enums_1.LogLevel.Info, `Model shadow (${this.subject}): the model says the coming morning ${verdict}, the trivial rule at ` +
+            `${ModelShadow.trivialSuppressSoc}% says it ${trivial} --> they ${agreed ? 'agree' : 'part'}; ` +
+            `${this._agreements} agreed, ${this._divergences} parted so far; ` +
+            `soc ${utils_1.Utils.round(currentSoc, 2)}%, ${detail}`);
+    }
+}
+exports.ModelShadow = ModelShadow;
+/**
+ * The state of charge in percent at or above which the trivial rule calls the coming morning safe.
+ *
+ * Deliberately not a setting. It is the yardstick the model is measured against, and a yardstick an
+ * installation can turn measures nothing: two plants would report agreement rates that cannot be compared,
+ * and a rate could be improved by moving the yardstick rather than the model.
+ */
+ModelShadow.trivialSuppressSoc = 55;

package/lib/utils/morning-reserve-dials.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The two thresholds the plant judges its coming morning by, read structurally off the energy manager's
+ * settings.
+ *
+ * Both describe the battery and its yield rather than whoever asks about them: "how low may the morning get"
+ * is a property of the battery, and "how little sun is no sun" a property of the plant's photovoltaic. Two
+ * consumers differ in how sure they want to be before they act, not in what the morning has to hold.
+ *
+ * Optional, because a manager that states neither cannot judge and none is invented for it - a verdict against
+ * a guessed reserve reads exactly like one against a stated reserve. Without them the plant says nothing and
+ * every consumer falls back to what needs no history.
+ *
+ * Not part of the published surface: it describes how the shared implementation reads a manager, not something
+ * a consumer of the library implements.
+ */
+export interface iMorningReserveDials {
+    /** The charge level in percent the coming morning's low is expected to stay above */
+    minimumMorningSocReserve?: number;
+    /** Below this many hours of sun left, no further yield is expected to change the outcome */
+    noSunThresholdHours?: number;
+}

package/lib/utils/morning-reserve-dials.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/utils/morning-verdict.d.ts

@@ -0,0 +1,5 @@
+/**
+ * What a decision stage predicts about the coming morning low: whether the state of charge will still clear
+ * the reserve by then.
+ */
+export type MorningVerdict = 'holds' | 'misses';

package/lib/utils/morning-verdict.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/utils/utils.d.ts

@@ -1,7 +1,6 @@
 import { CatchEmResult } from './catchEmResult';
 import { iTimePair } from '../interfaces';
 import { RGB } from './RGB';
-export declare const DAYMS: number;
 export declare class Utils {
     static get timeTilMidnight(): number;
     static catchEm<T>(promise: Promise<T>): Promise<CatchEmResult<T>>;
@@ -23,6 +22,13 @@ export declare class Utils {
     static nowTime(): iTimePair;
     static dateByTimeSpan(hours: number, minutes: number, now?: Date): Date;
     static positiveMod(number: number, mod: number): number;
+    /**
+     * Calculates the shortest angular distance between two degree values.
+     * @param degreeA - The first degree value
+     * @param degreeB - The second degree value
+     * @returns The distance in degrees, always between 0 and 180
+     */
+    static degreeDistance(degreeA: number, degreeB: number): number;
     static degreeInBetween(minDegree: number, maxDegree: number, degreeToCheck: number): boolean;
     private static deepOmit;
     static nextMatchingDate(hours?: number, minutes?: number, now?: Date): Date;

package/lib/utils/utils.js

@@ -3,16 +3,16 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Utils = exports.DAYMS = void 0;
+exports.Utils = void 0;
 const lodash_1 = __importDefault(require("lodash"));
 const logging_1 = require("../logging");
 const enums_1 = require("../enums");
 const i18n_1 = require("../i18n");
 const settings_service_1 = require("../settings-service");
-exports.DAYMS = 24 * 60 * 60 * 1000;
+const dayMs_1 = require("./dayMs");
 class Utils {
     static get timeTilMidnight() {
-        return new Date(Utils.nowMS() + exports.DAYMS).setHours(0, 0, 0, 0) - Utils.nowMS();
+        return new Date(Utils.nowMS() + dayMs_1.DAYMS).setHours(0, 0, 0, 0) - Utils.nowMS();
     }
     static async catchEm(promise) {
         return promise
@@ -175,8 +175,8 @@ class Utils {
     static beetweenDays(date, startDay, endDay) {
         const yearStart = new Date(date.getTime());
         yearStart.setMonth(0, 1);
-        const startDate = new Date(yearStart.getTime() + startDay * exports.DAYMS);
-        const endDate = new Date(yearStart.getTime() + endDay * exports.DAYMS);
+        const startDate = new Date(yearStart.getTime() + startDay * dayMs_1.DAYMS);
+        const endDate = new Date(yearStart.getTime() + endDay * dayMs_1.DAYMS);
         return date <= endDate && date >= startDate;
     }
     static nowTime() {
@@ -189,6 +189,16 @@ class Utils {
     static positiveMod(number, mod) {
         return ((number % mod) + mod) % mod;
     }
+    /**
+     * Calculates the shortest angular distance between two degree values.
+     * @param degreeA - The first degree value
+     * @param degreeB - The second degree value
+     * @returns The distance in degrees, always between 0 and 180
+     */
+    static degreeDistance(degreeA, degreeB) {
+        const delta = this.positiveMod(degreeA - degreeB, 360);
+        return delta > 180 ? 360 - delta : delta;
+    }
     static degreeInBetween(minDegree, maxDegree, degreeToCheck) {
         const modMin = this.positiveMod(minDegree, 360);
         const modMax = this.positiveMod(maxDegree, 360);