fix(cron): instantaneous-field provenance only — lifetime/day energies excluded, absent SOC contributes nothing (codex P2)

- composeObservedAt(inv, stationTs, stationSocKnown): fromInverter = any of gen/use/grid/batt power or SOC overridden; fromStation = any power still station-valued, or SOC station-known and not overridden; genTotal (history) never gates freshness; SOC absent on both sources is stored NULL and is no contributor
- 7 composition tests mirroring the real getLatestOpen cases (117 total)

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Author: THUNDER PHUM

.inbox/deyecloud/codex/review-0d8537e.md

@@ -0,0 +1,20 @@
+# Review 0d8537e — HOLD (1 P2)
+
+## P2: Count actual instantaneous sources, not missing lifetime energy or unknown SOC
+
+Location: `src/worker/deye.ts:416-427`.
+
+The conservative oldest-contributor rule is sound, and the preceding SOC-only / unrelated-point cases are fixed. But the contributor classification adds a station/latest source when ANY of six inverter fields is absent, regardless of whether that field is actually a station/latest observation:
+
+- `genTotal` comes from `tt.generationTotal` (day history, line 393), not `d` (station/latest). When history does not provide it it is a zero placeholder. Absence of `TotalActiveProduction` must not make an otherwise complete, fresh realtime inverter reading depend on stale/missing station/latest time.
+- When neither source reports SOC, `socKnown=false` and the worker stores SQL NULL. That is absence of an observation, not station evidence requiring a station timestamp.
+
+Actual worker+SQLite reproductions:
+
+1. Four powers + SOC all fresh from inverter, station timestamp four days old, no inverter lifetime meter -> original valid-fresh-recovery case regresses: `observedAt` becomes four days old, sample/telemetry dropped and frozen state remains. Supplying the unrelated lifetime point as a positive control lets the identical fresh realtime measurements store.
+2. Same complete five realtime fields, station timestamp absent -> `observedAt=null`, no samples; freshness remains unprovable indefinitely even with a consistently fresh inverter.
+3. Fresh four powers + lifetime meter, SOC absent on both sources (`socKnown=false`), station timestamp old -> drops the sample solely because the NULL SOC is counted as a station contribution.
+
+Scope the realtime contributor set to the values actually sourced and persisted as measurements. Keep lifetime/day energy provenance separate from instantaneous freshness; exclude absent SOC from source requirements. Preserve a station contribution for real fallback power/SOC values, including verified zero. Add actual composition/ingestion tests, not only tests of `observedAtOf` with precomputed `used` flags.
+
+Verified: 110/110 tests, typecheck, build, diff-check; prior partial/no-override cases and pure age cases pass; six-field inverter positive control and normal recovery/purge controls pass. Harness `.summary/review-088cb16.cjs` extended. No production or app source changes.

src/lib/__tests__/freeze.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { isFrozenReading, observedAtOf } from "../freeze";
+import { isFrozenReading, observedAtOf, composeObservedAt } from "../freeze";
 
 const NOW = 1_790_000_000, STALE = 720;
 describe("isFrozenReading — freshness of the value source, independent of monotonicity", () => {
@@ -27,3 +27,30 @@ describe("observedAtOf — oldest contributing source bounds freshness", () => {
   });
   it("nothing contributed → null", () => expect(observedAtOf([{ used: false, ts: S }])).toBeNull());
 });
+
+describe("composeObservedAt — actual Latest composition cases", () => {
+  const S = 1_790_000_000, OLD = 1_789_650_000; // fresh vs 4 days old
+  const full = (ts: number, extra: Partial<import("../freeze").InvFlow> = {}) => ({ genPower: 4000, usePower: 900, gridPower: -3000, battPower: 100, soc: 75, observedAt: ts, ...extra });
+  it("old station + fresh inverter with ALL 4 powers + SOC, NO lifetime point → fresh (lifetime is not instantaneous)", () => {
+    expect(composeObservedAt(full(S), OLD, true)).toBe(S);
+  });
+  it("old station + fresh inverter powers, SOC absent on BOTH → fresh (absent SOC contributes nothing)", () => {
+    expect(composeObservedAt(full(S, { soc: undefined }), OLD, false)).toBe(S);
+  });
+  it("old station + fresh inverter powers, SOC absent on inverter but known on station → station contributes → old", () => {
+    expect(composeObservedAt(full(S, { soc: undefined }), OLD, true)).toBe(OLD);
+  });
+  it("fresh station + 4-day-old device that only has SOC → device contributes → old", () => {
+    expect(composeObservedAt({ soc: 75, observedAt: OLD }, S, true)).toBe(OLD);
+  });
+  it("fresh station + device with no mapped field (e.g. only BatteryRatedCapacity) → station only → fresh", () => {
+    expect(composeObservedAt({ observedAt: null }, S, true)).toBe(S);
+    expect(composeObservedAt(null, S, true)).toBe(S);
+  });
+  it("zero values are real contributions (gen 0 at night from the inverter counts as inverter-sourced)", () => {
+    expect(composeObservedAt(full(S, { genPower: 0, gridPower: 0, battPower: 0 }), OLD, true)).toBe(S);
+  });
+  it("partial override with a timestamp-less device → unprovable", () => {
+    expect(composeObservedAt({ genPower: 4000, observedAt: null }, S, true)).toBeNull();
+  });
+});

src/lib/freeze.ts

@@ -27,3 +27,20 @@ export function observedAtOf(contributors: { used: boolean; ts: number | null }[
   if (used.some((c) => c.ts == null || !Number.isFinite(c.ts) || c.ts <= 0)) return null;
   return Math.min(...used.map((c) => c.ts as number));
 }
+
+// Provenance of the INSTANTANEOUS fields of a Latest record (gen/use/grid/batt
+// power + SOC). Lifetime/day-energy fields have their own (history) provenance
+// and never gate instantaneous freshness. SOC that neither source reported is
+// stored NULL and contributes nothing.
+export interface InvFlow { genPower?: number; usePower?: number; gridPower?: number; battPower?: number; soc?: number; observedAt: number | null }
+export function composeObservedAt(inv: InvFlow | null, stationTs: number | null, stationSocKnown: boolean): number | null {
+  const powers = ["genPower", "usePower", "gridPower", "battPower"] as const;
+  const invHas = (k: keyof InvFlow) => !!inv && (inv as any)[k] != null;
+  const fromInverter = !!inv && (powers.some(invHas) || invHas("soc"));
+  const socFromStation = !invHas("soc") && stationSocKnown;
+  const fromStation = !inv || powers.some((k) => !invHas(k)) || socFromStation;
+  return observedAtOf([
+    { used: fromStation, ts: stationTs },
+    { used: fromInverter, ts: inv ? inv.observedAt : null },
+  ]);
+}

src/worker/deye.ts

@@ -331,7 +331,7 @@ export async function getStationMeta(env: Env): Promise<Station> {
   return picked;
 }
 
-import { observedAtOf } from "../lib/freeze";
+import { composeObservedAt } from "../lib/freeze";
 
 // Open API is the only data source.
 export async function getLatest(env: Env, stationId?: string): Promise<Latest> {
@@ -409,26 +409,20 @@ async function getLatestOpen(env: Env, stationId?: string): Promise<Latest> {
   // (verified live): battery −=charge/+=discharge, grid +=import/−=export.
   try {
     const inv = await getInverterFlow(env, id);
-    // Each stored realtime field keeps a provenance flag: overridden by the
-    // inverter or left as the station value. The record's observation time is
-    // the OLDEST source that actually contributed a field (lib/freeze.ts) — a
-    // device snapshot that overrides nothing does not vouch for station values.
-    const realtime: (keyof typeof out)[] = ["genPower", "usePower", "gridPower", "battPower", "soc", "genTotal"];
-    let fromInverter = false;
+    // Instantaneous fields keep per-field provenance (inverter override vs.
+    // station value); the record's observation time is the OLDEST source that
+    // actually contributed one (lib/freeze.ts composeObservedAt). Lifetime
+    // genTotal and the day energies come from history and are NOT part of it.
+    const stationSocKnown = out.socKnown;
     if (inv) {
       if (inv.genPower != null) out.genPower = inv.genPower;
       if (inv.usePower != null) out.usePower = inv.usePower;
       if (inv.gridPower != null) { out.gridPower = inv.gridPower; out.gridStatus = inv.gridPower >= 0 ? "PURCHASE" : "REVERSE"; }
       if (inv.battPower != null) { out.battPower = inv.battPower; out.battStatus = inv.battPower > 20 ? "DISCHARGE" : inv.battPower < -20 ? "CHARGE" : "STATIC"; }
       if (inv.soc != null) { out.soc = inv.soc; out.socKnown = true; }
       if (inv.genTotal != null) out.genTotal = inv.genTotal; // lifetime kWh (not in station API)
-      fromInverter = realtime.some((k) => (inv as any)[k] != null);
     }
-    const fromStation = !inv || realtime.some((k) => (inv as any)[k] == null); // at least one field still station-sourced
-    out.observedAt = observedAtOf([
-      { used: fromStation, ts: toSec(d.lastUpdateTime) },
-      { used: fromInverter, ts: inv ? inv.observedAt : null },
-    ]);
+    out.observedAt = composeObservedAt(inv, toSec(d.lastUpdateTime), stationSocKnown);
   } catch {}
   return out;
 }