@xdelivered/emberflow 0.2.0

package/dist/src/nodes/pradar/logic.d.ts

@@ -0,0 +1,189 @@
+/**
+ * EV charge scheduler — pure decision logic for a demo solar/EV charging flow.
+ * Every decision is a pure function so an Emberflow flow can drive it
+ * deterministically (constants, formulas, thresholds, priorities, edge cases).
+ *
+ * Two notes on shape:
+ *  1. `getThresholds` takes trends as an explicit parameter rather than reading
+ *     a module-level rolling-reading window.
+ *  2. Time-dependent helpers take a `now` ISO string (default: current time) and
+ *     resolve the wall-clock HOUR from UTC (`getUTCHours`) so scenarios pinned
+ *     with a `now` (…Z) are reproducible on any machine. Sunrise/sunset come
+ *     from suncalc as absolute UTC instants, so `isSolarHours` /
+ *     `hoursUntilSunset` are machine-independent.
+ */
+export declare const LAT = 52.52;
+export declare const LON = 13.405;
+export declare const EV_TARGET_BATTERY = 80;
+export declare const EV_SOLAR_TARGET = 90;
+export declare const EV_CAPACITY_KWH = 77.4;
+export declare const EV_CHARGE_RATE_KW = 2.3;
+export declare const EV_LOW_BATTERY = 50;
+export declare const EV_NIGHT_CHARGE_BELOW = 35;
+export declare const START_SURPLUS_W = 1500;
+export declare const STOP_SURPLUS_W = 500;
+export declare const START_MIN_SOC = 30;
+export declare const STOP_MIN_SOC = 20;
+export declare const COOLDOWN_MS: number;
+export declare const PREDICTIVE_BATTERY_SOC = 90;
+export declare const PREDICTIVE_MIN_PPV = 2000;
+export declare const SUNSET_HOURS_THRESHOLD = 2;
+export declare const GOLDEN_HOUR_START_W = 800;
+export declare const GOLDEN_HOUR_STOP_W = 200;
+export declare const MIN_SESSION_KWH = 0.5;
+export declare const TREND_WINDOW = 6;
+export type EvChargeState = 'idle' | 'waiting' | 'charging' | 'cooldown' | 'night_charging';
+export interface Reading {
+    time?: number;
+    surplus: number;
+    homeSoc: number;
+    ppv: number;
+}
+export interface Forecast {
+    remainingKwh: number;
+    strongHoursLeft: number;
+}
+export interface SunClock {
+    isSolarHours: boolean;
+    hoursUntilSunset: number;
+    sunrise: string;
+    sunset: string;
+    /** UTC wall-clock hour (0–23). */
+    hour: number;
+    /** True inside the 23:00–05:00 night-charge window. */
+    isNightWindow: boolean;
+}
+/** Sun position + derived time flags for the given instant/location. */
+export declare function sunTimes(now?: string, lat?: number, lon?: number): SunClock;
+export interface SurplusResult {
+    surplus: number;
+    /** 'export' when grid export is positive, else 'ppv-load'. */
+    branch: 'export' | 'ppv-load';
+}
+/**
+ * Verbatim surplus calc (evaluateCharge):
+ *   surplus = gridExport > 0 ? gridExport : max(0, ppv - loadPower)
+ */
+export declare function computeSurplus(ppv: number, loadPower: number, gridExport: number): SurplusResult;
+/** How many kWh the EV needs to reach target (verbatim evKwhNeeded). */
+export declare function evKwhNeeded(currentPct: number, target?: number): number;
+/**
+ * Estimate deliverable kWh from remaining solar (verbatim estimateSessionKwh).
+ * With a forecast: remaining kWh capped by charge rate over the hours left.
+ * Without: assume current surplus sustains for the remaining sun hours.
+ */
+export declare function estimateSessionKwh(surplusW: number, sunHoursLeft: number, forecast: Forecast | null): number;
+/** Per-cycle slope of `key` across the reading window (verbatim getTrend). */
+export declare function getTrend(readings: Reading[], key: 'surplus' | 'homeSoc' | 'ppv'): number;
+export interface TrendWindow {
+    surplusTrend: number;
+    socTrend: number;
+    ppvTrend: number;
+    stdDev: number;
+    cooldownMs: number;
+}
+/**
+ * Dynamic cooldown from surplus volatility (verbatim getCooldownMs):
+ *   < 3 readings → default 10 min
+ *   stdDev < 200 → stable → 5 min
+ *   stdDev > 800 → volatile → 15 min
+ *   else → default 10 min
+ */
+export declare function getCooldownMs(readings: Reading[]): number;
+/** stdDev of surplus across the window (0 for <3 readings, mirroring the cooldown gate). */
+export declare function surplusStdDev(readings: Reading[]): number;
+/** Bundle the trend-window derivations one Trend Window node emits. */
+export declare function computeTrendWindow(readings: Reading[]): TrendWindow;
+export interface Trends {
+    surplusTrend: number;
+    socTrend: number;
+}
+export interface ThresholdResult {
+    startW: number;
+    stopW: number;
+    skipReason: string | null;
+    reasons: string[];
+}
+/**
+ * Verbatim port of getThresholds. The ONLY change: `trends` (surplus + home-SOC
+ * per-cycle slopes) is passed in explicitly instead of read from module state
+ * via `getTrend(...)`. Defaults to zero slopes (no trend override), matching a
+ * cold start with fewer than two readings.
+ */
+export declare function getThresholds(homeSoc: number, ppv: number, sunHoursLeft: number, evBattery: number | null, forecast: Forecast | null, trends?: Trends): ThresholdResult;
+export interface UnscheduledGuardInput {
+    charging: boolean;
+    state: EvChargeState;
+    surplus: number;
+    startW: number;
+    skipReason: string | null;
+    homeSoc: number;
+    effectiveMinSoc: number;
+}
+export declare function shouldStopUnscheduledCharge({ charging, state, surplus, startW, skipReason, homeSoc, effectiveMinSoc, }: UnscheduledGuardInput): boolean;
+export interface NightChargeDecision {
+    shouldCharge: boolean;
+    factors: string[];
+}
+export declare function getNightChargeDecision(evBattery: number, tomorrowKwh: number | null): NightChargeDecision;
+export type ChargeAction = 'start' | 'stop' | 'hold_waiting' | 'hold_charging';
+export interface ChargeDecisionInput {
+    state: 'idle' | 'waiting' | 'charging';
+    surplus: number;
+    startW: number;
+    stopW: number;
+    homeSoc: number;
+    skipReason: string | null;
+}
+export interface ChargeDecisionResult {
+    action: ChargeAction;
+    nextState: EvChargeState;
+    reason: string;
+}
+/**
+ * Verbatim port of evaluateCharge's idle/waiting/charging branch (lines
+ * 629–705). effectiveMinSoc and effectiveStopSoc are both 0 in production
+ * (morning home SOC near 0% is normal after overnight discharge — the surplus
+ * threshold already prevents grid import), so the SOC comparisons never trip
+ * here; they are preserved verbatim for fidelity.
+ */
+export declare function decideCharge({ state, surplus, startW, stopW, homeSoc, skipReason, }: ChargeDecisionInput): ChargeDecisionResult;
+export type TargetBranch = 'notPlugged' | 'atTarget' | 'belowTarget';
+export interface TargetCheckResult {
+    branch: TargetBranch;
+    effectiveTarget: number;
+    reason: string;
+}
+/**
+ * Verbatim port of the plugged-in / at-target gate. Effective target is the
+ * solar target (90%) during solar hours, else the grid target (80%).
+ */
+export declare function checkTarget(pluggedIn: boolean, evBattery: number | null, isSolarHours: boolean): TargetCheckResult;
+export type ReconcileDecision = 'adopt' | 'hold';
+export interface ReconcileResult {
+    decision: ReconcileDecision;
+    nextState: EvChargeState;
+    reason: string;
+}
+/**
+ * Verbatim port: if the car is charging but the scheduler isn't in a
+ * charging/night/cooldown state, and current rules allow it, adopt the session.
+ */
+export declare function reconcile(charging: boolean, state: EvChargeState): ReconcileResult;
+export interface NightChargeEstimate {
+    neededKwh: number;
+    hoursToCharge: number;
+}
+/** kWh needed to reach the grid target + hours at the home charge rate (verbatim). */
+export declare function nightChargeEstimate(evBattery: number): NightChargeEstimate;
+export interface MorningSummary {
+    lines: string[];
+    outlook: 'good' | 'tight' | 'unlikely' | 'at-target' | 'not-applicable';
+}
+/**
+ * Verbatim port of the morning-summary outlook lines. `remainingKwh` is today's
+ * remaining solar forecast; `evBattery`/`pluggedIn` come from the Kia snapshot.
+ * Outlook thresholds: Good when remaining > needed×1.5, Tight when > needed,
+ * else Unlikely; EV at/above the solar target reports "at target".
+ */
+export declare function morningSummary(homeSoc: number | null, evBattery: number | null, pluggedIn: boolean, todayKwh: number | null, remainingKwh: number | null, strongHoursLeft: number | null): MorningSummary;

package/dist/src/nodes/pradar/logic.js

@@ -0,0 +1,370 @@
+import * as SunCalc from 'suncalc';
+/**
+ * EV charge scheduler — pure decision logic for a demo solar/EV charging flow.
+ * Every decision is a pure function so an Emberflow flow can drive it
+ * deterministically (constants, formulas, thresholds, priorities, edge cases).
+ *
+ * Two notes on shape:
+ *  1. `getThresholds` takes trends as an explicit parameter rather than reading
+ *     a module-level rolling-reading window.
+ *  2. Time-dependent helpers take a `now` ISO string (default: current time) and
+ *     resolve the wall-clock HOUR from UTC (`getUTCHours`) so scenarios pinned
+ *     with a `now` (…Z) are reproducible on any machine. Sunrise/sunset come
+ *     from suncalc as absolute UTC instants, so `isSolarHours` /
+ *     `hoursUntilSunset` are machine-independent.
+ */
+// Demo location (Berlin). Overridable per call.
+export const LAT = 52.52;
+export const LON = 13.405;
+// EV constants (verbatim)
+export const EV_TARGET_BATTERY = 80; // Target for night/grid charging
+export const EV_SOLAR_TARGET = 90; // Target for solar excess charging (AC is gentle, free energy)
+export const EV_CAPACITY_KWH = 77.4; // EV6 Long Range usable capacity
+export const EV_CHARGE_RATE_KW = 2.3; // Home EVSE charge rate (10A single phase)
+export const EV_LOW_BATTERY = 50; // Below this, EV gets priority over home battery
+export const EV_NIGHT_CHARGE_BELOW = 35; // Below this at night, force a grid charge to 80%
+// Thresholds (watts) — reactive mode (verbatim)
+export const START_SURPLUS_W = 1500;
+export const STOP_SURPLUS_W = 500;
+export const START_MIN_SOC = 30;
+export const STOP_MIN_SOC = 20;
+export const COOLDOWN_MS = 10 * 60_000;
+// Predictive thresholds (verbatim)
+export const PREDICTIVE_BATTERY_SOC = 90;
+export const PREDICTIVE_MIN_PPV = 2000;
+export const SUNSET_HOURS_THRESHOLD = 2;
+export const GOLDEN_HOUR_START_W = 800;
+export const GOLDEN_HOUR_STOP_W = 200;
+// Worth-it calculation: minimum kWh a session must deliver to justify the wake +
+// command overhead (~13 min at 2.3kW — below this it's not worth the wear).
+export const MIN_SESSION_KWH = 0.5;
+// Trend tracking — rolling window of last N readings (verbatim).
+export const TREND_WINDOW = 6;
+function resolveNow(now) {
+    return now ? new Date(now) : new Date();
+}
+/** Sun position + derived time flags for the given instant/location. */
+export function sunTimes(now, lat = LAT, lon = LON) {
+    const d = resolveNow(now);
+    const times = SunCalc.getTimes(d, lat, lon);
+    // @types/suncalc types sunrise/sunset as possibly null (polar edge cases);
+    // for this latitude they are always present. Fall back to the instant itself.
+    const sunrise = times.sunrise ?? d;
+    const sunset = times.sunset ?? d;
+    const isSolarHours = d > sunrise && d < sunset;
+    const hoursUntilSunset = Math.max(0, (sunset.getTime() - d.getTime()) / 3_600_000);
+    const hour = d.getUTCHours();
+    // Verbatim night gate: production returns early "outside night" when
+    // `hour >= 5 && hour < 23`, i.e. the night window is hour >= 23 || hour < 5.
+    const isNightWindow = hour >= 23 || hour < 5;
+    return {
+        isSolarHours,
+        hoursUntilSunset,
+        sunrise: sunrise.toISOString(),
+        sunset: sunset.toISOString(),
+        hour,
+        isNightWindow,
+    };
+}
+/**
+ * Verbatim surplus calc (evaluateCharge):
+ *   surplus = gridExport > 0 ? gridExport : max(0, ppv - loadPower)
+ */
+export function computeSurplus(ppv, loadPower, gridExport) {
+    if (gridExport > 0)
+        return { surplus: gridExport, branch: 'export' };
+    return { surplus: Math.max(0, ppv - loadPower), branch: 'ppv-load' };
+}
+/** How many kWh the EV needs to reach target (verbatim evKwhNeeded). */
+export function evKwhNeeded(currentPct, target = EV_TARGET_BATTERY) {
+    const pctNeeded = target - currentPct;
+    if (pctNeeded <= 0)
+        return 0;
+    return (pctNeeded / 100) * EV_CAPACITY_KWH;
+}
+/**
+ * Estimate deliverable kWh from remaining solar (verbatim estimateSessionKwh).
+ * With a forecast: remaining kWh capped by charge rate over the hours left.
+ * Without: assume current surplus sustains for the remaining sun hours.
+ */
+export function estimateSessionKwh(surplusW, sunHoursLeft, forecast) {
+    if (forecast) {
+        return Math.min(forecast.remainingKwh, EV_CHARGE_RATE_KW * sunHoursLeft);
+    }
+    return (Math.min(surplusW, EV_CHARGE_RATE_KW * 1000) / 1000) * sunHoursLeft;
+}
+// ============================================================================
+// Trends + dynamic cooldown (verbatim getTrend / getCooldownMs)
+// ============================================================================
+/** Per-cycle slope of `key` across the reading window (verbatim getTrend). */
+export function getTrend(readings, key) {
+    if (readings.length < 2)
+        return 0;
+    const first = readings[0];
+    const last = readings[readings.length - 1];
+    const cycles = readings.length - 1;
+    return (last[key] - first[key]) / cycles;
+}
+/**
+ * Dynamic cooldown from surplus volatility (verbatim getCooldownMs):
+ *   < 3 readings → default 10 min
+ *   stdDev < 200 → stable → 5 min
+ *   stdDev > 800 → volatile → 15 min
+ *   else → default 10 min
+ */
+export function getCooldownMs(readings) {
+    if (readings.length < 3)
+        return COOLDOWN_MS;
+    const surpluses = readings.map((r) => r.surplus);
+    const mean = surpluses.reduce((a, b) => a + b, 0) / surpluses.length;
+    const variance = surpluses.reduce((sum, s) => sum + (s - mean) ** 2, 0) / surpluses.length;
+    const stdDev = Math.sqrt(variance);
+    if (stdDev < 200)
+        return 5 * 60_000;
+    if (stdDev > 800)
+        return 15 * 60_000;
+    return COOLDOWN_MS;
+}
+/** stdDev of surplus across the window (0 for <3 readings, mirroring the cooldown gate). */
+export function surplusStdDev(readings) {
+    if (readings.length < 1)
+        return 0;
+    const surpluses = readings.map((r) => r.surplus);
+    const mean = surpluses.reduce((a, b) => a + b, 0) / surpluses.length;
+    const variance = surpluses.reduce((sum, s) => sum + (s - mean) ** 2, 0) / surpluses.length;
+    return Math.sqrt(variance);
+}
+/** Bundle the trend-window derivations one Trend Window node emits. */
+export function computeTrendWindow(readings) {
+    return {
+        surplusTrend: getTrend(readings, 'surplus'),
+        socTrend: getTrend(readings, 'homeSoc'),
+        ppvTrend: getTrend(readings, 'ppv'),
+        stdDev: surplusStdDev(readings),
+        cooldownMs: getCooldownMs(readings),
+    };
+}
+/**
+ * Verbatim port of getThresholds. The ONLY change: `trends` (surplus + home-SOC
+ * per-cycle slopes) is passed in explicitly instead of read from module state
+ * via `getTrend(...)`. Defaults to zero slopes (no trend override), matching a
+ * cold start with fewer than two readings.
+ */
+export function getThresholds(homeSoc, ppv, sunHoursLeft, evBattery, forecast, trends = { surplusTrend: 0, socTrend: 0 }) {
+    const reasons = [];
+    // Default thresholds must cover the EV charge rate (2.3kW) so we don't
+    // primarily import from grid. Home battery can buffer the small shortfall.
+    let startW = 2000;
+    let stopW = 800;
+    let skipReason = null;
+    const evUrgent = evBattery !== null && evBattery < EV_LOW_BATTERY;
+    const homeHasBuffer = homeSoc >= 30;
+    if (evUrgent) {
+        startW = 1200;
+        stopW = 400;
+        reasons.push(`ev urgent: ${evBattery}% < ${EV_LOW_BATTERY}%, accepting some grid`);
+    }
+    else if (homeHasBuffer) {
+        startW = 1200;
+        stopW = 400;
+        reasons.push(`home ${homeSoc}% has buffer — EV priority, home tops up EV shortfall`);
+    }
+    else {
+        reasons.push(`home ${homeSoc}% flat — need ${startW}W solar to avoid grid import`);
+    }
+    // --- Predictive: battery nearly full + strong production → export imminent ---
+    if (homeSoc >= PREDICTIVE_BATTERY_SOC && ppv >= PREDICTIVE_MIN_PPV) {
+        startW = Math.min(startW, 500);
+        stopW = Math.min(stopW, 200);
+        reasons.push(`predictive: home SOC ${homeSoc}% + ppv ${Math.round(ppv)}W → export imminent`);
+    }
+    // --- Golden hour: sun setting soon, capture remaining solar ---
+    if (sunHoursLeft > 0 && sunHoursLeft <= SUNSET_HOURS_THRESHOLD && !skipReason) {
+        startW = Math.min(startW, GOLDEN_HOUR_START_W);
+        stopW = Math.min(stopW, GOLDEN_HOUR_STOP_W);
+        reasons.push(`golden hour: ${sunHoursLeft.toFixed(1)}h until sunset`);
+    }
+    // --- Worth-it check: is the remaining solar enough to justify a session? ---
+    const inBonusZone = evBattery !== null && evBattery >= EV_TARGET_BATTERY && evBattery < EV_SOLAR_TARGET;
+    if (evBattery !== null && forecast && !skipReason) {
+        const estimatedKwh = estimateSessionKwh(ppv, sunHoursLeft, forecast);
+        const target = inBonusZone ? EV_SOLAR_TARGET : EV_TARGET_BATTERY;
+        const needed = evKwhNeeded(evBattery, target);
+        if (estimatedKwh < MIN_SESSION_KWH && needed > 2) {
+            skipReason = `not worth it: ~${estimatedKwh.toFixed(1)}kWh available vs ${needed.toFixed(0)}kWh needed`;
+            reasons.push(skipReason);
+        }
+        if (evBattery >= 65 && estimatedKwh < 1.5) {
+            skipReason = `EV at ${evBattery}%, only ~${estimatedKwh.toFixed(1)}kWh solar remaining — not worth a session`;
+            reasons.push(skipReason);
+        }
+    }
+    // --- Trend-aware: surplus rising fast → be more aggressive ---
+    const surplusTrend = trends.surplusTrend;
+    if (surplusTrend > 200) {
+        startW = Math.min(startW, 1000);
+        reasons.push(`trend: surplus rising ${Math.round(surplusTrend)}W/cycle`);
+    }
+    // --- SOC climbing fast → battery about to fill ---
+    const socTrend = trends.socTrend;
+    if (socTrend > 2 && homeSoc > 75) {
+        startW = Math.min(startW, 600);
+        reasons.push(`trend: home SOC rising ${socTrend.toFixed(1)}%/cycle from ${homeSoc}%`);
+    }
+    return { startW, stopW, skipReason, reasons };
+}
+export function shouldStopUnscheduledCharge({ charging, state, surplus, startW, skipReason, homeSoc, effectiveMinSoc, }) {
+    if (!charging)
+        return false;
+    if (state === 'charging' || state === 'cooldown' || state === 'night_charging')
+        return false;
+    if (skipReason)
+        return true;
+    if (surplus < startW)
+        return true;
+    if (homeSoc < effectiveMinSoc)
+        return true;
+    return false;
+}
+export function getNightChargeDecision(evBattery, tomorrowKwh) {
+    const factors = [];
+    const criticallyLow = evBattery < EV_NIGHT_CHARGE_BELOW;
+    const poorForecast = tomorrowKwh !== null && tomorrowKwh < 10; // < 10kWh expected = poor day
+    const evModerate = evBattery < 65;
+    if (criticallyLow) {
+        factors.push(`EV critically low at ${evBattery}% (< ${EV_NIGHT_CHARGE_BELOW}%)`);
+    }
+    else if (evModerate && poorForecast) {
+        factors.push(`EV at ${evBattery}% with poor forecast tomorrow (${tomorrowKwh?.toFixed(1)}kWh)`);
+    }
+    return { shouldCharge: factors.length > 0, factors };
+}
+/**
+ * Verbatim port of evaluateCharge's idle/waiting/charging branch (lines
+ * 629–705). effectiveMinSoc and effectiveStopSoc are both 0 in production
+ * (morning home SOC near 0% is normal after overnight discharge — the surplus
+ * threshold already prevents grid import), so the SOC comparisons never trip
+ * here; they are preserved verbatim for fidelity.
+ */
+export function decideCharge({ state, surplus, startW, stopW, homeSoc, skipReason, }) {
+    const effectiveMinSoc = 0;
+    const effectiveStopSoc = 0;
+    if (state === 'idle' || state === 'waiting') {
+        if (skipReason) {
+            return { action: 'hold_waiting', nextState: 'waiting', reason: skipReason };
+        }
+        if (surplus >= startW && homeSoc >= effectiveMinSoc) {
+            return {
+                action: 'start',
+                nextState: 'cooldown',
+                reason: `surplus ${Math.round(surplus)}W ≥ ${startW}W threshold, starting charge`,
+            };
+        }
+        if (surplus < startW) {
+            return {
+                action: 'hold_waiting',
+                nextState: 'waiting',
+                reason: `surplus ${Math.round(surplus)}W < ${startW}W threshold`,
+            };
+        }
+        return {
+            action: 'hold_waiting',
+            nextState: 'waiting',
+            reason: `home SOC ${homeSoc}% < ${effectiveMinSoc}% threshold`,
+        };
+    }
+    // state === 'charging'
+    if (surplus < stopW || homeSoc < effectiveStopSoc) {
+        const reason = surplus < stopW
+            ? `surplus ${Math.round(surplus)}W < ${stopW}W, stopping charge`
+            : `home SOC ${homeSoc}% < ${effectiveStopSoc}%, stopping charge`;
+        return { action: 'stop', nextState: 'cooldown', reason };
+    }
+    return {
+        action: 'hold_charging',
+        nextState: 'charging',
+        reason: `charging — surplus ${Math.round(surplus)}W, home SOC ${homeSoc}%`,
+    };
+}
+/**
+ * Verbatim port of the plugged-in / at-target gate. Effective target is the
+ * solar target (90%) during solar hours, else the grid target (80%).
+ */
+export function checkTarget(pluggedIn, evBattery, isSolarHours) {
+    const effectiveTarget = isSolarHours ? EV_SOLAR_TARGET : EV_TARGET_BATTERY;
+    if (!pluggedIn) {
+        return { branch: 'notPlugged', effectiveTarget, reason: 'not plugged in' };
+    }
+    if (evBattery !== null && evBattery >= effectiveTarget) {
+        return {
+            branch: 'atTarget',
+            effectiveTarget,
+            reason: `battery at ${evBattery}% (target ${effectiveTarget}%)`,
+        };
+    }
+    return {
+        branch: 'belowTarget',
+        effectiveTarget,
+        reason: `battery at ${evBattery ?? '?'}% below target ${effectiveTarget}%`,
+    };
+}
+/**
+ * Verbatim port: if the car is charging but the scheduler isn't in a
+ * charging/night/cooldown state, and current rules allow it, adopt the session.
+ */
+export function reconcile(charging, state) {
+    if (charging && state !== 'charging' && state !== 'night_charging' && state !== 'cooldown') {
+        return {
+            decision: 'adopt',
+            nextState: 'charging',
+            reason: 'reconciled: car was already charging and scheduler conditions are met',
+        };
+    }
+    return { decision: 'hold', nextState: state, reason: 'no reconciliation needed' };
+}
+/** kWh needed to reach the grid target + hours at the home charge rate (verbatim). */
+export function nightChargeEstimate(evBattery) {
+    const neededKwh = evKwhNeeded(evBattery); // target = EV_TARGET_BATTERY (80)
+    return { neededKwh, hoursToCharge: neededKwh / EV_CHARGE_RATE_KW };
+}
+/**
+ * Verbatim port of the morning-summary outlook lines. `remainingKwh` is today's
+ * remaining solar forecast; `evBattery`/`pluggedIn` come from the Kia snapshot.
+ * Outlook thresholds: Good when remaining > needed×1.5, Tight when > needed,
+ * else Unlikely; EV at/above the solar target reports "at target".
+ */
+export function morningSummary(homeSoc, evBattery, pluggedIn, todayKwh, remainingKwh, strongHoursLeft) {
+    const homeStr = homeSoc ?? '?';
+    const evStr = evBattery ?? '?';
+    const plugged = pluggedIn ? 'plugged in' : 'not plugged in';
+    const todayStr = todayKwh != null ? todayKwh.toFixed(1) : '?';
+    const strongStr = strongHoursLeft ?? '?';
+    const remainStr = remainingKwh != null ? remainingKwh.toFixed(1) : '?';
+    const lines = [
+        `Home battery: ${homeStr}%`,
+        `EV: ${evStr}% (${plugged})`,
+        `Solar forecast: ${todayStr}kWh today (${remainStr}kWh remaining, ${strongStr}h strong sun)`,
+    ];
+    let outlook = 'not-applicable';
+    if (pluggedIn && typeof evBattery === 'number' && evBattery < EV_SOLAR_TARGET) {
+        const needed = evKwhNeeded(evBattery, EV_SOLAR_TARGET);
+        const remaining = remainingKwh ?? 0;
+        if (remaining > needed * 1.5) {
+            outlook = 'good';
+            lines.push(`Outlook: Good — ${remaining.toFixed(1)}kWh forecast should cover ${needed.toFixed(1)}kWh EV needs`);
+        }
+        else if (remaining > needed) {
+            outlook = 'tight';
+            lines.push(`Outlook: Tight — ${remaining.toFixed(1)}kWh forecast vs ${needed.toFixed(1)}kWh EV needs (home battery gets priority)`);
+        }
+        else {
+            outlook = 'unlikely';
+            lines.push(`Outlook: Unlikely to fully charge EV today (${remaining.toFixed(1)}kWh forecast vs ${needed.toFixed(1)}kWh needed)`);
+        }
+    }
+    else if (typeof evBattery === 'number' && evBattery >= EV_SOLAR_TARGET) {
+        outlook = 'at-target';
+        lines.push(`EV already at target (${EV_SOLAR_TARGET}%) — no charging needed`);
+    }
+    return { lines, outlook };
+}

package/dist/src/nodes/pradar/nodes.d.ts

@@ -0,0 +1,42 @@
+import type { NodeRegistry } from '../../engine/index.js';
+/** Shape of {EV_DEMO_BASE_URL}/api/growatt/status we consume (inverter status endpoint). */
+export interface GrowattStatusJson {
+    soc?: number;
+    ppv?: number;
+    loadPower?: number;
+    gridExport?: number;
+}
+/** Shape of {EV_DEMO_BASE_URL}/api/vehicle/status we consume. */
+export interface KiaStatusJson {
+    resMsg?: {
+        vehicleStatusInfo?: {
+            vehicleStatus?: {
+                evStatus?: {
+                    batteryStatus?: number;
+                    batteryPlugin?: number;
+                    batteryCharge?: boolean;
+                };
+            };
+        };
+    };
+}
+/** The live tick fields the scheduler derives before running the decision logic. */
+export interface EvTickLiveFields {
+    ppv: number;
+    loadPower: number;
+    gridExport: number;
+    homeSoc: number;
+    evBattery: number | null;
+    pluggedIn: boolean;
+    charging: boolean;
+}
+/**
+ * Maps a Growatt status + Kia vehicle status into the flow's live tick fields,
+ * homeSoc = growatt.soc, ppv/loadPower/gridExport straight off GrowattStatus
+ * (loadPower is already mapped from sd.pLocalLoad inside getGrowattStatus), and
+ * evStatus at resMsg.vehicleStatusInfo.vehicleStatus.evStatus →
+ * batteryStatus→evBattery, (batteryPlugin ?? 0) > 0→pluggedIn,
+ * batteryCharge === true→charging. Pure so it's unit-testable without fetch.
+ */
+export declare function mapTickTelemetry(growatt: GrowattStatusJson | undefined, kia: KiaStatusJson | undefined): EvTickLiveFields;
+export declare function registerPradarNodes(registry: NodeRegistry): void;