hoffmation-base 3.8.0 → 4.1.0

package/lib/services/weather/weather-history-backfill.js

@@ -0,0 +1,247 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WeatherHistoryBackfill = void 0;
+const logging_1 = require("../../logging");
+const enums_1 = require("../../enums");
+const HTTPSOptions_1 = require("../HTTPSOptions");
+const https_service_1 = require("../https-service");
+const settings_service_1 = require("../../settings-service");
+const utils_1 = require("../../utils");
+/**
+ * Fills the gaps in the stored daily weather aggregates from the One Call 3.0 day summary endpoint.
+ *
+ * Its own service instead of a method on the weather service: that one serves the live forecast, while this
+ * one walks a window of past days and must stay bounded and throttled. The full recorded history is far larger
+ * than a day's request quota, so the fitting window is the hard limit and the throttle keeps an accidentally
+ * widened window from draining the quota in one burst.
+ */
+class WeatherHistoryBackfill {
+    /**
+     * Fetches the daily weather aggregates that are missing within the fitting window and stores them, plus the
+     * running day's aggregate on every run. Past days that are already stored are not fetched again, so a
+     * service restart does not cost quota; the running day always is, because it is a forecast that moves. A past
+     * day that was already fetched on the running day is not fetched again until the next calendar day.
+     * @param persist - The persistence to read the present days from and to write the fetched ones to
+     * @param referenceDate - The running day; the window ends on it, inclusive
+     * @param historyWindowDays - Length of the history window in days; calls are bounded by it plus one
+     * @param fetcher - The fetcher to use, defaults to the configured One Call 3.0 day summary endpoint
+     * @param throttleMs - Milliseconds to wait between two calls
+     * @returns - The number of days that were fetched and handed to the persistence. Not the number that
+     * arrived: `persistWeatherDaySummary` reports nothing back, so whether a row landed cannot be seen from
+     * here. Do not read this as a count of stored rows - look in the table for that.
+     */
+    static async run(persist, referenceDate, historyWindowDays, fetcher, throttleMs = WeatherHistoryBackfill.defaultThrottleMs) {
+        if (persist === undefined) {
+            logging_1.ServerLogService.writeLog(enums_1.LogLevel.Debug, 'WeatherHistoryBackfill: no persistence configured --> nothing to do');
+            return 0;
+        }
+        if (historyWindowDays < 1) {
+            logging_1.ServerLogService.writeLog(enums_1.LogLevel.Debug, `WeatherHistoryBackfill: window of ${historyWindowDays} days --> nothing to do`);
+            return 0;
+        }
+        const activeFetcher = fetcher !== null && fetcher !== void 0 ? fetcher : WeatherHistoryBackfill.createOpenWeatherFetcher();
+        if (activeFetcher === undefined) {
+            logging_1.ServerLogService.writeLog(enums_1.LogLevel.Warn, 'WeatherHistoryBackfill: no usable weather configuration --> skipped');
+            return 0;
+        }
+        const days = WeatherHistoryBackfill.windowDays(referenceDate, historyWindowDays);
+        const present = new Set((await persist.getWeatherDaySummaries(days[0], days[days.length - 1])).map((summary) => WeatherHistoryBackfill.dayKey(summary.date)));
+        // The last day of the window is the running one. Its aggregate is a forecast and moves through the day,
+        // so it is fetched on every run and the upsert overwrites it; a past day is archive and does not change,
+        // so a stored one is never paid for twice.
+        const runningDay = WeatherHistoryBackfill.dayKey(days[days.length - 1]);
+        if (WeatherHistoryBackfill.attemptedPastDaysRecordedOn !== runningDay) {
+            WeatherHistoryBackfill.resetAttemptedPastDays();
+            WeatherHistoryBackfill.attemptedPastDaysRecordedOn = runningDay;
+        }
+        let fetched = 0;
+        // Handed to the persistence, not confirmed as arrived - persistWeatherDaySummary reports nothing back.
+        let handedOver = 0;
+        let heldBack = 0;
+        for (const day of days) {
+            const key = WeatherHistoryBackfill.dayKey(day);
+            if (key !== runningDay && present.has(key)) {
+                continue;
+            }
+            if (key !== runningDay && WeatherHistoryBackfill.attemptedPastDays.has(key)) {
+                heldBack++;
+                continue;
+            }
+            if (fetched > 0 && throttleMs > 0) {
+                await utils_1.Utils.delay(throttleMs);
+            }
+            fetched++;
+            if (key !== runningDay) {
+                // Noted before the outcome is known, on purpose - see {@link attemptedPastDays}.
+                WeatherHistoryBackfill.attemptedPastDays.add(key);
+            }
+            const summary = await activeFetcher(day);
+            if (summary === undefined) {
+                continue;
+            }
+            persist.persistWeatherDaySummary(summary);
+            handedOver++;
+        }
+        logging_1.ServerLogService.writeLog(handedOver > 0 ? enums_1.LogLevel.Info : enums_1.LogLevel.Debug, `WeatherHistoryBackfill: handed ${handedOver} of ${fetched} fetched day(s) to the persistence within the last ` +
+            `${historyWindowDays} days plus today, ${heldBack} day(s) held back after an earlier fetch today`);
+        return handedOver;
+    }
+    /**
+     * Forgets which past days were already fetched, so the next run offers the whole window again. Called by
+     * `run` itself on a change of the running day; separate so a test can start from a known state.
+     */
+    static resetAttemptedPastDays() {
+        WeatherHistoryBackfill.attemptedPastDays.clear();
+        WeatherHistoryBackfill.attemptedPastDaysRecordedOn = undefined;
+    }
+    /**
+     * Builds the fetcher against the One Call 3.0 day summary endpoint.
+     * @param settings - The weather settings to use, defaults to the configured ones
+     * @returns - The fetcher, or `undefined` when there is no location or no key to work with
+     */
+    static createOpenWeatherFetcher(settings) {
+        var _a;
+        if (settings === void 0) { settings = (_a = settings_service_1.SettingsService.settings) === null || _a === void 0 ? void 0 : _a.weather; }
+        if (settings === undefined || !settings.appid || !settings.lattitude || !settings.longitude) {
+            return undefined;
+        }
+        const location = settings;
+        return (date) => WeatherHistoryBackfill.fetchDaySummary(location, date);
+    }
+    /**
+     * The days of the fitting window, oldest first, **including the running day**. The running day is in there
+     * on purpose: the gate reads today's cloud cover and maximum temperature out of the same table and through
+     * the same reader as the history, so that both sides of the fit are the same quantity from the same field.
+     * That is one extra call per run - the alternative was the gate deriving today's figures from a different
+     * product, which measurably is not the same number.
+     * @param referenceDate - The running day
+     * @param historyWindowDays - Length of the history window in days
+     * @returns - `historyWindowDays + 1` day starts, the last of which is the running day
+     */
+    static windowDays(referenceDate, historyWindowDays) {
+        const midnight = new Date(referenceDate);
+        midnight.setHours(0, 0, 0, 0);
+        const days = [];
+        for (let offset = historyWindowDays; offset >= 0; offset--) {
+            const day = new Date(midnight);
+            // Calendar arithmetic instead of subtracting milliseconds, so a daylight saving change does not shift
+            // every older day of the window by an hour.
+            day.setDate(day.getDate() - offset);
+            days.push(day);
+        }
+        return days;
+    }
+    static async fetchDaySummary(settings, date) {
+        const day = WeatherHistoryBackfill.dayKey(date);
+        return new Promise((resolve) => {
+            // HTTPSOptions logs the path it is constructed with, so it is constructed with a redacted one and the
+            // real query - which carries location and key - is set afterwards. The repository is public.
+            // Do NOT collapse these two into one constructor call: that puts the key into a log line. The guard is
+            // "keeps key and location out of the path HTTPSOptions is constructed with" in
+            // test/services/dachs-history-persistence.test.ts.
+            const options = new HTTPSOptions_1.HTTPSOptions(WeatherHistoryBackfill.host, `/data/3.0/onecall/day_summary (${day})`, {}, 'GET', 443);
+            options.path =
+                `/data/3.0/onecall/day_summary?lat=${settings.lattitude}&lon=${settings.longitude}` +
+                    `&date=${day}&appid=${settings.appid}&units=metric`;
+            // This promise settles because the callback always comes: `HTTPSService.request` reports every way a
+            // request can end - an answer, an exhausted retry chain, a failing socket, an endpoint that accepts the
+            // connection and then stays silent - to its callback exactly once, and bounds each attempt by its own
+            // time limit. A failure arrives as `HTTPSService.failureStatusCode`, which is not 200 and is discarded
+            // below like any other unusable answer. Nothing here has to watch the clock as well; a second deadline
+            // would only be able to fire before the retry does and throw away the answer it was about to bring.
+            https_service_1.HTTPSService.request(options, '', 1, (response, statusCode) => {
+                resolve(WeatherHistoryBackfill.parseDaySummary(response, statusCode, date, day));
+            });
+        });
+    }
+    static parseDaySummary(response, statusCode, date, day) {
+        var _a, _b, _c, _d;
+        if (statusCode !== 200) {
+            // Neither the answer nor the request is logged: both carry the key and the location.
+            logging_1.ServerLogService.writeLog(enums_1.LogLevel.Warn, `WeatherHistoryBackfill: day summary for ${day} answered ${statusCode}`);
+            return undefined;
+        }
+        const parsed = utils_1.Utils.guardedFunction(() => JSON.parse(response), undefined, `WeatherHistoryBackfill: unreadable day summary for ${day}`);
+        // Each leaf is established as a number in a plausible range here rather than trusted from the shape
+        // above. This is the boundary: what passes is written into the table the start decision is read from,
+        // and nothing between here and that decision looks at the values again.
+        const cloudCover = WeatherHistoryBackfill.plausibleReading((_a = parsed === null || parsed === void 0 ? void 0 : parsed.cloud_cover) === null || _a === void 0 ? void 0 : _a.afternoon, 0, 100);
+        const tempMin = WeatherHistoryBackfill.plausibleReading((_b = parsed === null || parsed === void 0 ? void 0 : parsed.temperature) === null || _b === void 0 ? void 0 : _b.min, WeatherHistoryBackfill.minTemperature, WeatherHistoryBackfill.maxTemperature);
+        const tempMax = WeatherHistoryBackfill.plausibleReading((_c = parsed === null || parsed === void 0 ? void 0 : parsed.temperature) === null || _c === void 0 ? void 0 : _c.max, WeatherHistoryBackfill.minTemperature, WeatherHistoryBackfill.maxTemperature);
+        if (cloudCover === undefined || tempMin === undefined || tempMax === undefined) {
+            // No substitute values: a made up cloud cover would be fitted as if it had been measured. A value
+            // outside its band is discarded exactly like a missing one, for the same reason.
+            logging_1.ServerLogService.writeLog(enums_1.LogLevel.Warn, `WeatherHistoryBackfill: incomplete day summary for ${day}`);
+            return undefined;
+        }
+        // Read AFTER the completeness check and deliberately outside it. The three fields above decide whether the
+        // day counts; precipitation must never be able to discard one. An endpoint that does not send the field,
+        // or a dry day it chooses to omit, would otherwise tear a hole into the history the start decision reads -
+        // a defect that would only show up as a gradually thinning window, weeks later. Absent stays absent all
+        // the way into the column; it is not filled with a 0, which would be an ordinary reading rather than a
+        // visibly missing one.
+        const precipitation = WeatherHistoryBackfill.plausibleReading((_d = parsed === null || parsed === void 0 ? void 0 : parsed.precipitation) === null || _d === void 0 ? void 0 : _d.total, 0, WeatherHistoryBackfill.maxPrecipitation);
+        const dayStart = new Date(date);
+        dayStart.setHours(0, 0, 0, 0);
+        return {
+            date: dayStart,
+            cloudCover: cloudCover,
+            tempMin: tempMin,
+            tempMax: tempMax,
+            precipitation: precipitation,
+        };
+    }
+    /**
+     * Establishes one field of the answer as a reading: a real number within the band its quantity can occupy.
+     *
+     * `typeof` rather than `Number(...)`: a value that has to be converted first is not a reading of the
+     * quantity, and converting would turn `null` into 0 and `""` into 0 - both of which pass every band. The
+     * band itself catches what is numeric but cannot be the quantity, `NaN` and the infinities included, since
+     * neither compares inside it.
+     * @param value - The field as it arrived
+     * @param min - Lowest value the quantity can take
+     * @param max - Highest value the quantity can take
+     * @returns - The reading, or undefined when the field is not one
+     */
+    static plausibleReading(value, min, max) {
+        if (typeof value !== 'number' || !Number.isFinite(value) || value < min || value > max) {
+            return undefined;
+        }
+        return value;
+    }
+    static dayKey(date) {
+        const month = `${date.getMonth() + 1}`.padStart(2, '0');
+        const day = `${date.getDate()}`.padStart(2, '0');
+        return `${date.getFullYear()}-${month}-${day}`;
+    }
+}
+exports.WeatherHistoryBackfill = WeatherHistoryBackfill;
+/** Milliseconds between two calls to the weather service. */
+WeatherHistoryBackfill.defaultThrottleMs = 1500;
+/**
+ * The band a daily air temperature in degrees Celsius can occupy. Wide on purpose - it is there to reject
+ * what cannot be a temperature at all, not to second guess the weather service on a hot afternoon. The
+ * bounds sit outside the coldest and the hottest reading ever recorded on the planet.
+ */
+WeatherHistoryBackfill.minTemperature = -95;
+WeatherHistoryBackfill.maxTemperature = 60;
+/**
+ * The most millimetres of precipitation a single day can carry. Wide on purpose, like the temperature band:
+ * it rejects what cannot be a daily rainfall at all, it does not second guess the weather service on a
+ * thunderstorm. The bound sits above the highest daily total ever recorded on the planet.
+ */
+WeatherHistoryBackfill.maxPrecipitation = 2000;
+WeatherHistoryBackfill.host = 'api.openweathermap.org';
+/**
+ * The past days of the window that were already fetched on the running day, and the running day that was
+ * recorded on.
+ *
+ * The attempt is remembered, not its outcome: a past day is archive, so a second fetch on the same calendar
+ * day cannot yield anything the first one did not, whatever became of the first. That also covers the fetch
+ * that succeeded while the write did not land - `persistWeatherDaySummary` reports nothing back, so a
+ * failing write is invisible from here and would otherwise cost the full window once per run, and the
+ * backfill runs far more often than once a day. The running day is remembered alongside, so a passing outage
+ * heals on the next calendar day instead of staying suppressed until a restart.
+ */
+WeatherHistoryBackfill.attemptedPastDays = new Set();
+WeatherHistoryBackfill.attemptedPastDaysRecordedOn = undefined;

package/lib/services/weather/weather-service.js

@@ -314,18 +314,43 @@ class WeatherService {
             return;
         }
         const host = 'api.openweathermap.org';
-        const path = `/data/3.0/onecall?lat=${WeatherService.latitude}&lon=${WeatherService.longitude}&appid=${WeatherService.appID}&units=metric&lang=de`;
+        // HTTPSOptions logs the path it is constructed with, so it is constructed with a redacted one and the
+        // real query - which carries key and location - is set afterwards. The repository is public and an
+        // operator runs at Debug, which is the level that log line goes out on.
+        // Do NOT collapse these two into one constructor call: that puts the key into a log line. The guard is
+        // "carries key and location in the request and in no log line" in test/services/weather-service.test.ts.
+        const options = new HTTPSOptions_1.HTTPSOptions(host, '/data/3.0/onecall (forecast)', {}, 'GET', 443);
+        options.path =
+            `/data/3.0/onecall?lat=${WeatherService.latitude}&lon=${WeatherService.longitude}` +
+                `&appid=${WeatherService.appID}&units=metric&lang=de`;
         logging_1.ServerLogService.writeLog(enums_1.LogLevel.Debug, 'Send WeatherAPi Request for data update.');
-        https_service_1.HTTPSService.request(new HTTPSOptions_1.HTTPSOptions(host, path, {}, 'GET', 443), '', 5, (response) => {
+        https_service_1.HTTPSService.request(options, '', 5, (response, statusCode) => {
+            if (statusCode < 200 || statusCode >= 300) {
+                // Everything outside the successful range ends the update here, and the last forecast stays in place:
+                // an old forecast is a worse answer than a fresh one, an error page is none at all.
+                // This covers both ways a request can miss its forecast. `HTTPSService.failureStatusCode` means there
+                // was no answer to begin with, and any other code means the endpoint answered something that is not
+                // one - a refused key answers 401, an exhausted quota 429. The body cannot be what decides that:
+                // those answers are readable JSON as well, so parsing them succeeds and yields a WeatherResponse
+                // whose every field is undefined.
+                // Only the code is named: the request carries the key and the answer mirrors the coordinate back.
+                logging_1.ServerLogService.writeLog(enums_1.LogLevel.Warn, `WeatherAPi request answered ${statusCode} --> no forecast update`);
+                return;
+            }
             logging_1.ServerLogService.writeLog(enums_1.LogLevel.Debug, 'WeatherAPi Response erhalten');
-            logging_1.ServerLogService.writeLog(enums_1.LogLevel.DeepTrace, `WeatherAPi Response: ${response}`);
+            // The length rather than the body: the answer mirrors the coordinate of the request back, so a raw
+            // dump writes the location of the plant into the log even though it carries no key itself.
+            logging_1.ServerLogService.writeLog(enums_1.LogLevel.DeepTrace, `WeatherAPi Response of ${response.length} characters received`);
             utils_1.Utils.guardedFunction(() => {
                 const responseObj = JSON.parse(response);
                 WeatherService.processHourlyWeather(responseObj);
                 for (const dataUpdateCbsKey in this._dataUpdateCbs) {
                     this._dataUpdateCbs[dataUpdateCbsKey]();
                 }
-            }, this, `Response from Weather API call at https://${host}/${path}: ${response}`);
+            }, this, 
+            // Neither the request nor the answer is named here: the first carries the key, the second mirrors
+            // the location back. The status of the call is already reported by the two lines above.
+            'WeatherService: the answer of the weather API could not be processed');
         });
     }
     static recalcAzimuth() {

package/lib/settings-service-instance.js

@@ -32,7 +32,9 @@ class SettingsServiceInstance {
                 return lat;
             }
         }
-        return 51.529556852253826;
+        // A coarse fallback so the sun times resolve at all when no location is configured. Deliberately not a
+        // site: one decimal is roughly city scale, and this default is public.
+        return 51.0;
     }
     get longitude() {
         var _a, _b;
@@ -42,7 +44,8 @@ class SettingsServiceInstance {
                 return longitude;
             }
         }
-        return 7.097266042276687;
+        // Coarse for the same reason as the latitude above.
+        return 7.0;
     }
     initialize(config) {
         this.settings = config;

package/lib/settingsObjects/deviceSettings/dachsSettings.d.ts

@@ -31,6 +31,12 @@ export declare class DachsDeviceSettings extends ActuatorSettings implements iDa
     winterMinimumHeatStorageTemp: number;
     /** @inheritDoc */
     winterMinimumPreNightHeatStorageTemp: number;
+    /** @inheritDoc */
+    summerWarmWaterDesiredMaxTemp: number;
+    /** @inheritDoc */
+    dachsRatedElectricalWattage: number;
+    /** @inheritDoc */
+    dachsConversionFactor: number;
     fromPartialObject(data: Partial<DachsDeviceSettings>): void;
     toJSON(): Partial<DachsDeviceSettings>;
 }

package/lib/settingsObjects/deviceSettings/dachsSettings.js

@@ -3,6 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DachsDeviceSettings = void 0;
 const utils_1 = require("../../utils");
 const actuatorSettings_1 = require("./actuatorSettings");
+// Shared with the energy manager's settings rather than copied: the two would otherwise drift apart on what
+// counts as an unusable share, and an installation would be answered differently depending on which device
+// happened to read the value.
+const victronDeviceSettings_1 = require("./victronDeviceSettings");
 class DachsDeviceSettings extends actuatorSettings_1.ActuatorSettings {
     constructor() {
         super(...arguments);
@@ -36,9 +40,15 @@ class DachsDeviceSettings extends actuatorSettings_1.ActuatorSettings {
         this.winterMinimumHeatStorageTemp = 55;
         /** @inheritDoc */
         this.winterMinimumPreNightHeatStorageTemp = 65;
+        /** @inheritDoc */
+        this.summerWarmWaterDesiredMaxTemp = 58;
+        /** @inheritDoc */
+        this.dachsRatedElectricalWattage = 5500;
+        /** @inheritDoc */
+        this.dachsConversionFactor = 0.8;
     }
     fromPartialObject(data) {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s;
         this.disableHeatingRod = (_a = data.disableHeatingRod) !== null && _a !== void 0 ? _a : this.disableHeatingRod;
         this.disableDachsOwnWW = (_b = data.disableDachsOwnWW) !== null && _b !== void 0 ? _b : this.disableDachsOwnWW;
         this.disableDachsTemporarily = (_c = data.disableDachsTemporarily) !== null && _c !== void 0 ? _c : this.disableDachsTemporarily;
@@ -58,6 +68,9 @@ class DachsDeviceSettings extends actuatorSettings_1.ActuatorSettings {
         this.winterMinimumHeatStorageTemp = (_p = data.winterMinimumHeatStorageTemp) !== null && _p !== void 0 ? _p : this.winterMinimumHeatStorageTemp;
         this.winterMinimumPreNightHeatStorageTemp =
             (_q = data.winterMinimumPreNightHeatStorageTemp) !== null && _q !== void 0 ? _q : this.winterMinimumPreNightHeatStorageTemp;
+        this.summerWarmWaterDesiredMaxTemp = (_r = data.summerWarmWaterDesiredMaxTemp) !== null && _r !== void 0 ? _r : this.summerWarmWaterDesiredMaxTemp;
+        this.dachsRatedElectricalWattage = (_s = data.dachsRatedElectricalWattage) !== null && _s !== void 0 ? _s : this.dachsRatedElectricalWattage;
+        this.dachsConversionFactor = (0, victronDeviceSettings_1.acceptedShare)('dachsConversionFactor', data.dachsConversionFactor, this.dachsConversionFactor);
         super.fromPartialObject(data);
     }
     toJSON() {

package/lib/settingsObjects/deviceSettings/victronDeviceSettings.d.ts

@@ -1,4 +1,35 @@
 import { DeviceSettings } from './deviceSettings';
+/**
+ * Takes over a setting that has to lie between 0 and 1, or keeps the value in force and reports the refusal.
+ *
+ * Kept rather than clamped, and that is the whole decision: 90 written for "90 percent" clamps to 1 and turns
+ * a dial nobody touched to its extreme - a coverage demanding every single reading of a day, a quantile at
+ * the maximum of the sample, a conversion factor that loses nothing at all. Each of those is a plausible
+ * looking number, and a plausible looking number is exactly the one an operator never goes looking for. The
+ * value in force is the documented default, the refused input is named in the log, and no unusable input
+ * quietly becomes a different plant.
+ *
+ * Deliberately loud rather than thrown: a settings file is read at startup, and one mistyped share must not
+ * cost the whole installation its automation.
+ *
+ * Lives here rather than on the settings base class only because of how this change was cut; it is shared by
+ * every settings class that carries a share and belongs next to them.
+ * @param name - The setting, so the log line names what was refused
+ * @param value - What was handed in, or undefined when the caller set nothing
+ * @param current - The value in force, kept whenever the input is unusable
+ * @returns - The value to use from now on
+ */
+export declare function acceptedShare(name: string, value: number | undefined, current: number): number;
+/**
+ * Reports a history window shorter than the number of days the fit demands before it produces anything.
+ *
+ * Reported rather than corrected: which of the two numbers the operator meant cannot be told from here, and
+ * the combination is not dangerous - the fit simply never yields a band and the decision falls back to the
+ * rung that needs no history. Only nobody would ever see why it never got past that rung.
+ * @param windowDays - The length of the sliding window in days
+ * @param minimumDays - How many usable days the fit demands
+ */
+export declare function reportImpossibleWindow(windowDays: number, minimumDays: number): void;
 export declare class VictronDeviceSettings extends DeviceSettings {
     /**
      * The default time interval in minutes for battery-change reporting regardless of battery level.
@@ -47,6 +78,91 @@ export declare class VictronDeviceSettings extends DeviceSettings {
      * @default 10000
      */
     batteryCapacityWattage: number;
+    /**
+     * The share of the expected consumption readings a recorded day has to carry before its window sum is
+     * counted at all, between 0 and 1.
+     *
+     * A dial of the plant rather than of whoever reads its history: an incompletely covered night adds up to
+     * too little, therefore looks like a frugal night, pulls the quantile down and makes the resulting bound
+     * too optimistic - and two readers who disagree about what counts as a covered day of the same plant would
+     * be answering about two different plants. Deliberately strict, because a bound that is too optimistic
+     * suppresses, and a wrong suppression has no way back: the morning is simply below the reserve by then.
+     * @default 0.9
+     */
+    historyMinimumDayCoverage: number;
+    /**
+     * The quantile of the recorded consumption windows a model free bound is calculated with, between 0 and 1.
+     * An upper quantile rather than the median, because the bound has to hold on a heavy night and not on half
+     * of them.
+     * @default 0.9
+     */
+    historyConsumptionQuantile: number;
+    /**
+     * How many usable consumption window sums are needed before that quantile means anything at all.
+     *
+     * An upper quantile of one night is that night, and of two nights it sits all but on their maximum - so a
+     * single quiet night would yield a high bound and a suppression with nothing behind it. Deliberately its
+     * own number rather than a shared minimum with the day count a model fit needs: that one protects the
+     * stability of a fit, this one protects the meaning of a quantile.
+     * @default 10
+     */
+    historyMinimumConsumptionDays: number;
+    /**
+     * The state of charge in percent the coming morning's low is expected to stay above.
+     *
+     * A property of the battery and therefore stated once, here: "how low may the morning get" is the same
+     * question whichever device asks it, and two numbers for one battery would let a plant judge one and the
+     * same morning twice. Where consumers legitimately differ is how sure they want to be before they act, and
+     * that is the split between the verdicts that need no model and the ones that do - see
+     * {@link iMorningReserveVerdict.measured}, not a second reserve.
+     *
+     * It is also the threshold the model shadow measures against, and a shadow whose sample is split across two
+     * thresholds measures nothing - see {@link ModelShadow}.
+     * @default 20
+     */
+    minimumMorningSocReserve: number;
+    /**
+     * Below this many remaining sun hours no further photovoltaic yield is expected to change the coming
+     * morning.
+     *
+     * Plant wide next to the reserve, because it describes this installation's photovoltaic rather than whoever
+     * asks: the last half hour before sunset yields the same nothing for every consumer.
+     * @default 0.5
+     */
+    noSunThresholdHours: number;
+    /**
+     * The length of the sliding window in days the history is read and fitted from. Older days describe a
+     * differently grown installation and are deliberately left out.
+     *
+     * Stated once for the whole plant, here, because it says how much of the recorded data is telling enough to
+     * answer with - a property of that data and not of whoever asks. Every consumer of the history asks the
+     * same question, and a second window meant a second read and a second paid backfill of the same days.
+     *
+     * The default is a starting point, not a finding: it has not been established against recorded data. In the
+     * back test the estimate gets monotonically worse the longer the window is, and a window of sixty days
+     * already scores worse than the trivial threshold rule. Treat this value as unproven until a run against
+     * the recorded history has produced a number.
+     * @default 90
+     */
+    historyWindowDays: number;
+    /**
+     * How many usable historical days are needed before the weights are fitted at all. Below this number no
+     * band is produced at all and every consumer falls back to what needs no history.
+     *
+     * Plant wide for the same reason {@link historyWindowDays} is: how much evidence makes a fit meaningful is a
+     * property of the recorded data.
+     * @default 15
+     */
+    historyMinimumDays: number;
+    /**
+     * How many standard deviations of the residuals each band edge lies away from the point estimate.
+     *
+     * Plant wide, because the band is part of the answer rather than of the judgement made on it. A consumer
+     * that one day wants edges of its own width reads {@link iEnergyHistoryOutlook.residualSigma} and forms
+     * them; it does not fit a second model.
+     * @default 1.0
+     */
+    historyBandSigma: number;
     /**
      * The normal base consumption of the house in wattage
      * @default 600