@mxpicture/tesla-superchargers-mate 0.1.62 → 0.1.63

package/db/migrations/20260907181456_refs_precision_checks.sql

@@ -0,0 +1,183 @@
+-- pic_refs: the precision `hours` needs now that pic_refs_v divides by it, and
+-- two invariants stated as CHECK constraints.
+--
+-- (1) hours: 2 -> 6 dp. It was a display value, which is why 20260903171045
+--     moved mean_draw_kw off it and onto the raw interval. It stops being one
+--     here: pic_refs_v's gross_mean_draw_kw becomes
+--     gross_dropped_kwh / gross_hours, so `hours` is a divisor one level up --
+--     and rounding a divisor is what caused that defect in the first place. At
+--     2 dp the resulting error on gross_mean_draw_kw reaches 5.9455 kW and two
+--     sub-18-second refs round to a zero divisor and vanish; at 6 dp the error
+--     is 0.0020 kW and nothing vanishes. It also keeps a row self-consistent:
+--     at 2 dp, 354 of 700 rows would show a gross_mean_draw_kw that does not
+--     reconcile with the gross_hours printed beside it.
+--
+--     Nothing else moves. mean_draw_kw at 3 dp (1 W), cost_per_kwh at 4 (the
+--     0.08 EUR/kWh band the column exists to resolve) and the rest are terminal
+--     display values that feed no computation, and each scale was chosen for
+--     what its column measures.
+--
+-- (2) efficiency > 0. Four generation expressions carried NULLIF(efficiency, 0)
+--     to keep a zero out of a divisor. All that could ever do was turn a broken
+--     row into a silent NULL; stating the invariant once, checked on write, is
+--     the same guarantee and a better failure. A car with efficiency = 0 now
+--     fails the build loudly, which is consistent with what already happens for
+--     a NULL efficiency (review Md-6). The NULLIF then comes out of those four
+--     expressions, each keeping its round() scale exactly as it was.
+--
+-- (3) end_date >= start_date. An interval that runs backwards gives a negative
+--     `hours` and a mean_draw_kw whose sign means the opposite of what it says.
+--     Both CHECKs are validated against every existing row on ADD, and both
+--     return zero rows on the dev history; re-run the two SELECTs in section 8
+--     of the plan against production before applying.
+--
+-- The order below is forced, not stylistic. PG18 refuses SET EXPRESSION on a
+-- VIRTUAL generated column while the table carries any CHECK constraint
+-- (0A000), so every expression has to be rewritten before the CHECKs go on --
+-- and a later migration that wants to change one of these columns has to drop
+-- the two CHECKs, rewrite, and add them back. migrate:down runs the same
+-- sequence in reverse for the same reason.
+--
+-- Every column touched is VIRTUAL, so SET EXPRESSION is a catalog edit and none
+-- of this rewrites the table. The two CHECKs do scan it once.
+--
+-- docs/plans/2026-09-07_pic-refs-gross-ratios.md, sections 5 and 8.
+-- migrate:up
+ALTER TABLE pic_refs
+ALTER COLUMN hours
+SET
+  EXPRESSION AS (
+    round(
+      EXTRACT(
+        epoch
+        FROM
+          (end_date - start_date)
+      ) / 3600.0,
+      6
+    )
+  );
+
+ALTER TABLE pic_refs
+ALTER COLUMN mean_draw_kw
+SET
+  EXPRESSION AS (
+    round(
+      (start_range_km - end_range_km) * efficiency / NULLIF(
+        EXTRACT(
+          epoch
+          FROM
+            (end_date - start_date)
+        ) / 3600.0,
+        0::NUMERIC
+      ),
+      3
+    )
+  );
+
+ALTER TABLE pic_refs
+ALTER COLUMN dropped_kwh
+SET
+  EXPRESSION AS ((start_range_km - end_range_km) * efficiency);
+
+ALTER TABLE pic_refs
+ALTER COLUMN kwh_per_real_1km
+SET
+  EXPRESSION AS (
+    round(
+      (start_range_km - end_range_km) * efficiency / NULLIF(real_km, 0::NUMERIC),
+      6
+    )
+  );
+
+ALTER TABLE pic_refs
+ALTER COLUMN cost_per_kwh
+SET
+  EXPRESSION AS (
+    CASE
+      WHEN start_range_km < end_range_km THEN NULL
+      ELSE round(
+        cost / NULLIF(
+          (start_range_km - end_range_km) * efficiency,
+          0::NUMERIC
+        ),
+        4
+      )
+    END
+  );
+
+ALTER TABLE pic_refs
+ADD CONSTRAINT pic_refs_efficiency_positive CHECK (efficiency > 0);
+
+ALTER TABLE pic_refs
+ADD CONSTRAINT pic_refs_date_order CHECK (end_date >= start_date);
+
+-- migrate:down
+ALTER TABLE pic_refs
+DROP CONSTRAINT IF EXISTS pic_refs_date_order;
+
+ALTER TABLE pic_refs
+DROP CONSTRAINT IF EXISTS pic_refs_efficiency_positive;
+
+ALTER TABLE pic_refs
+ALTER COLUMN cost_per_kwh
+SET
+  EXPRESSION AS (
+    CASE
+      WHEN start_range_km < end_range_km THEN NULL
+      ELSE round(
+        cost / NULLIF(
+          (start_range_km - end_range_km) * NULLIF(efficiency, 0),
+          0::NUMERIC
+        ),
+        4
+      )
+    END
+  );
+
+ALTER TABLE pic_refs
+ALTER COLUMN kwh_per_real_1km
+SET
+  EXPRESSION AS (
+    round(
+      (start_range_km - end_range_km) * NULLIF(efficiency, 0) / NULLIF(real_km, 0::NUMERIC),
+      6
+    )
+  );
+
+ALTER TABLE pic_refs
+ALTER COLUMN dropped_kwh
+SET
+  EXPRESSION AS (
+    (start_range_km - end_range_km) * NULLIF(efficiency, 0)
+  );
+
+ALTER TABLE pic_refs
+ALTER COLUMN mean_draw_kw
+SET
+  EXPRESSION AS (
+    round(
+      (start_range_km - end_range_km) * NULLIF(efficiency, 0) / NULLIF(
+        EXTRACT(
+          epoch
+          FROM
+            (end_date - start_date)
+        ) / 3600.0,
+        0::NUMERIC
+      ),
+      3
+    )
+  );
+
+ALTER TABLE pic_refs
+ALTER COLUMN hours
+SET
+  EXPRESSION AS (
+    round(
+      EXTRACT(
+        epoch
+        FROM
+          (end_date - start_date)
+      ) / 3600.0,
+      2
+    )
+  );

package/db/schema.sql

@@ -415,17 +415,19 @@ CREATE TABLE public.pic_refs (
     real_km numeric(8,4),
     used_cp_ids integer[],
     cost numeric(6,2),
-    hours numeric GENERATED ALWAYS AS (round((EXTRACT(epoch FROM (end_date - start_date)) / 3600.0), 2)),
-    mean_draw_kw numeric GENERATED ALWAYS AS (round((((start_range_km - end_range_km) * NULLIF(efficiency, (0)::numeric)) / NULLIF((EXTRACT(epoch FROM (end_date - start_date)) / 3600.0), (0)::numeric)), 3)),
+    hours numeric GENERATED ALWAYS AS (round((EXTRACT(epoch FROM (end_date - start_date)) / 3600.0), 6)),
+    mean_draw_kw numeric GENERATED ALWAYS AS (round((((start_range_km - end_range_km) * efficiency) / NULLIF((EXTRACT(epoch FROM (end_date - start_date)) / 3600.0), (0)::numeric)), 3)),
     dropped_km numeric GENERATED ALWAYS AS ((start_range_km - end_range_km)),
-    dropped_kwh numeric GENERATED ALWAYS AS (((start_range_km - end_range_km) * NULLIF(efficiency, (0)::numeric))),
-    kwh_per_real_1km numeric GENERATED ALWAYS AS (round((((start_range_km - end_range_km) * NULLIF(efficiency, (0)::numeric)) / NULLIF(real_km, (0)::numeric)), 6)),
+    dropped_kwh numeric GENERATED ALWAYS AS (((start_range_km - end_range_km) * efficiency)),
+    kwh_per_real_1km numeric GENERATED ALWAYS AS (round((((start_range_km - end_range_km) * efficiency) / NULLIF(real_km, (0)::numeric)), 6)),
     cost_per_real_100km numeric GENERATED ALWAYS AS (round(((cost * (100)::numeric) / NULLIF(real_km, (0)::numeric)), 2)),
     cost_per_kwh numeric GENERATED ALWAYS AS (
 CASE
     WHEN (start_range_km < end_range_km) THEN NULL::numeric
-    ELSE round((cost / NULLIF(((start_range_km - end_range_km) * NULLIF(efficiency, (0)::numeric)), (0)::numeric)), 4)
-END)
+    ELSE round((cost / NULLIF(((start_range_km - end_range_km) * efficiency), (0)::numeric)), 4)
+END),
+    CONSTRAINT pic_refs_date_order CHECK ((end_date >= start_date)),
+    CONSTRAINT pic_refs_efficiency_positive CHECK ((efficiency > (0)::numeric))
 );
 
 
@@ -2669,17 +2671,17 @@ CREATE VIEW public.pic_refs_v AS
             ELSE r.cost
         END AS dropped_cost,
         CASE
-            WHEN (r.ref_type = 'charge'::public.pic_ref_type) THEN ((- r.cost) - COALESCE(i.cost, 0.0))
-            ELSE (r.cost + COALESCE(i.cost, 0.0))
+            WHEN (r.ref_type = 'charge'::public.pic_ref_type) THEN (- s.gross_cost)
+            ELSE s.gross_cost
         END AS gross_dropped_cost,
-    (r.cost + COALESCE(i.cost, 0.0)) AS gross_cost,
-    (r.hours + COALESCE(i.hours, 0.0)) AS gross_hours,
-    (r.mean_draw_kw + COALESCE(i.mean_draw_kw, 0.0)) AS gross_mean_draw_kw,
-    (r.dropped_km + COALESCE(i.dropped_km, 0.0)) AS gross_dropped_km,
-    (r.dropped_kwh + COALESCE(i.dropped_kwh, 0.0)) AS gross_dropped_kwh,
-    (r.kwh_per_real_1km + COALESCE(i.kwh_per_real_1km, 0.0)) AS gross_kwh_per_real_1km,
-    (r.cost_per_real_100km + COALESCE(i.cost_per_real_100km, 0.0)) AS gross_cost_per_real_100km,
-    (r.cost_per_kwh + COALESCE(i.cost_per_kwh, 0.0)) AS gross_cost_per_kwh,
+    s.gross_cost,
+    s.gross_hours,
+    g.gross_mean_draw_kw,
+    s.gross_dropped_km,
+    s.gross_dropped_kwh,
+    g.gross_kwh_per_real_1km,
+    g.gross_cost_per_real_100km,
+    g.gross_cost_per_kwh,
     sm.seed_address_id AS start_seed_address_id,
     em.seed_address_id AS end_seed_address_id,
     sm.cluster_id AS start_cluster_id,
@@ -2700,8 +2702,8 @@ CREATE VIEW public.pic_refs_v AS
         END AS end_address_type,
     COALESCE(sg.name, (sa.address)::character varying, (sa_fallback.address)::character varying) AS start_address,
     COALESCE(eg.name, (ea.address)::character varying, (ea_fallback.address)::character varying) AS end_address
-   FROM (((((((((public.pic_refs r
-     LEFT JOIN public.pic_refs i ON (((i.ref_type = 'idle'::public.pic_ref_type) AND (r.ref_type = 'drive'::public.pic_ref_type) AND (i.next_type = r.ref_type) AND (i.next_id = r.ref_id))))
+   FROM (((((((((((public.pic_refs r
+     LEFT JOIN public.pic_refs i ON (((i.ref_type = 'idle'::public.pic_ref_type) AND (r.ref_type = 'drive'::public.pic_ref_type) AND (i.car_id = r.car_id) AND (i.next_type = r.ref_type) AND (i.next_id = r.ref_id))))
      LEFT JOIN public.pic_cluster_map_v sm ON ((sm.address_id = r.start_address_id)))
      LEFT JOIN public.pic_cluster_map_v em ON ((em.address_id = r.end_address_id)))
      LEFT JOIN public.pic_addresses_v sa ON ((sa.id = sm.seed_address_id)))
@@ -2710,6 +2712,17 @@ CREATE VIEW public.pic_refs_v AS
      LEFT JOIN public.pic_addresses_v ea_fallback ON ((ea_fallback.id = r.end_address_id)))
      LEFT JOIN public.geofences sg ON ((sg.id = r.start_geofence_id)))
      LEFT JOIN public.geofences eg ON ((eg.id = r.end_geofence_id)))
+     CROSS JOIN LATERAL ( SELECT (r.cost + COALESCE(i.cost, 0.0)) AS gross_cost,
+            (r.hours + COALESCE(i.hours, 0.0)) AS gross_hours,
+            (r.dropped_km + COALESCE(i.dropped_km, 0.0)) AS gross_dropped_km,
+            (r.dropped_kwh + COALESCE(i.dropped_kwh, 0.0)) AS gross_dropped_kwh) s)
+     CROSS JOIN LATERAL ( SELECT round((s.gross_dropped_kwh / NULLIF(s.gross_hours, (0)::numeric)), 3) AS gross_mean_draw_kw,
+            round((s.gross_dropped_kwh / NULLIF(r.real_km, (0)::numeric)), 6) AS gross_kwh_per_real_1km,
+            round(((s.gross_cost * (100)::numeric) / NULLIF(r.real_km, (0)::numeric)), 2) AS gross_cost_per_real_100km,
+                CASE
+                    WHEN (s.gross_dropped_kwh <= (0)::numeric) THEN NULL::numeric
+                    ELSE round((s.gross_cost / s.gross_dropped_kwh), 4)
+                END AS gross_cost_per_kwh) g)
   WHERE ((r.ref_id > 0) AND (COALESCE(r.prev_id, 0) >= 0));
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mxpicture/tesla-superchargers-mate",
-  "version": "0.1.62",
+  "version": "0.1.63",
   "description": "TeslaMate integration",
   "type": "module",
   "author": "MXPicture",
@@ -50,7 +50,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@mxpicture/tesla-superchargers-generated": "^0.1.62",
+    "@mxpicture/tesla-superchargers-generated": "^0.1.63",
     "dbmate": "2.35.1",
     "postgres": "^3.4.9",
     "short-uuid": "^6.0.3",

package/sql/views.sql

@@ -1049,18 +1049,25 @@ SELECT
     WHEN r.ref_type = 'charge'::pic_ref_type THEN - r.cost
     ELSE r.cost
   END AS dropped_cost,
+  -- The gross_* block: this ref plus the idle that fed it. The extensive
+  -- quantities -- cost, hours, dropped_km, dropped_kwh -- are summed in `s`
+  -- and genuinely do add. The four ratios are recomputed over those sums in
+  -- `g` and are never added: the sum of two rates is not the rate over the
+  -- combined window. A 0.3 kW idle before a 25 kW drive reported 25.3 kW, and
+  -- adding the two EUR/kWh figures was out by up to 0.5853 -- seven times the
+  -- 0.08 EUR/kWh band that cost_per_kwh carries four decimals to resolve.
   CASE
-    WHEN r.ref_type = 'charge'::pic_ref_type THEN - r.cost - COALESCE(i.cost, 0.0)
-    ELSE r.cost + COALESCE(i.cost, 0.0)
+    WHEN r.ref_type = 'charge'::pic_ref_type THEN - s.gross_cost
+    ELSE s.gross_cost
   END AS gross_dropped_cost,
-  r.cost + COALESCE(i.cost, 0.0) AS gross_cost,
-  r.hours + COALESCE(i.hours, 0.0) AS gross_hours,
-  r.mean_draw_kw + COALESCE(i.mean_draw_kw, 0.0) AS gross_mean_draw_kw,
-  r.dropped_km + COALESCE(i.dropped_km, 0.0) AS gross_dropped_km,
-  r.dropped_kwh + COALESCE(i.dropped_kwh, 0.0) AS gross_dropped_kwh,
-  r.kwh_per_real_1km + COALESCE(i.kwh_per_real_1km, 0.0) AS gross_kwh_per_real_1km,
-  r.cost_per_real_100km + COALESCE(i.cost_per_real_100km, 0.0) AS gross_cost_per_real_100km,
-  r.cost_per_kwh + COALESCE(i.cost_per_kwh, 0.0) AS gross_cost_per_kwh,
+  s.gross_cost,
+  s.gross_hours,
+  g.gross_mean_draw_kw,
+  s.gross_dropped_km,
+  s.gross_dropped_kwh,
+  g.gross_kwh_per_real_1km,
+  g.gross_cost_per_real_100km,
+  g.gross_cost_per_kwh,
   sm.seed_address_id AS start_seed_address_id,
   em.seed_address_id AS end_seed_address_id,
   sm.cluster_id AS start_cluster_id,
@@ -1083,8 +1090,11 @@ SELECT
   COALESCE(eg.name, ea.address, ea_fallback.address) AS end_address
 FROM
   pic_refs r
+  -- next_type/next_id identify the idle on their own, but the pack replay is
+  -- per-car and the join says so.
   LEFT JOIN pic_refs i ON i.ref_type = 'idle'::pic_ref_type
   AND r.ref_type = 'drive'::pic_ref_type
+  AND i.car_id = r.car_id
   AND i.next_type = r.ref_type
   AND i.next_id = r.ref_id
   LEFT JOIN pic_cluster_map_v sm ON sm.address_id = r.start_address_id
@@ -1095,6 +1105,47 @@ FROM
   LEFT JOIN pic_addresses_v ea_fallback ON ea_fallback.id = r.end_address_id
   LEFT JOIN geofences sg ON sg.id = r.start_geofence_id
   LEFT JOIN geofences eg ON eg.id = r.end_geofence_id
+  -- Two chained LATERALs rather than generated columns on pic_refs: a
+  -- generation expression cannot reference another generated column, and
+  -- gross_mean_draw_kw needs both of `s`'s sums. Each returns exactly one row,
+  -- so neither changes the cardinality above.
+  CROSS JOIN LATERAL (
+    SELECT
+      r.cost + COALESCE(i.cost, 0.0) AS gross_cost,
+      r.hours + COALESCE(i.hours, 0.0) AS gross_hours,
+      r.dropped_km + COALESCE(i.dropped_km, 0.0) AS gross_dropped_km,
+      r.dropped_kwh + COALESCE(i.dropped_kwh, 0.0) AS gross_dropped_kwh
+  ) s
+  -- The ratios over those sums, each rounded to the scale of its per-row twin
+  -- so that gross_X and X read at the same precision. gross_hours is what
+  -- makes `hours` load-bearing rather than a display value, and why
+  -- 20260907181456 took it to 6 dp.
+  --
+  -- The per-km pair divides by r.real_km alone: an idle covers no distance, so
+  -- the drive's kilometres are the whole of the combined window's. That makes
+  -- both a per-trip fact with a legitimately heavy tail -- 24 of 320 drives
+  -- exceed 1 kWh/km, because a one-kilometre drive after a three-day park
+  -- genuinely did cost that much per km once standby is charged to it. The
+  -- car's own consumption rate is the adjacent kwh_per_real_1km on the same
+  -- row; the tail is not a defect and nothing here thresholds it away.
+  --
+  -- What the tail does break is averaging. Aggregate these as
+  -- sum(numerator) / sum(denominator), never avg(ratio): over the same drives,
+  -- sum(gross_dropped_kwh) / sum(real_km) is 0.2212 kWh/km where
+  -- avg(gross_kwh_per_real_1km) reads 0.4740. Both sums are columns of this
+  -- view.
+  CROSS JOIN LATERAL (
+    SELECT
+      round(s.gross_dropped_kwh / NULLIF(s.gross_hours, 0), 3) AS gross_mean_draw_kw,
+      round(s.gross_dropped_kwh / NULLIF(r.real_km, 0), 6) AS gross_kwh_per_real_1km,
+      round(s.gross_cost * 100 / NULLIF(r.real_km, 0), 2) AS gross_cost_per_real_100km,
+      -- The same guard as pic_refs.cost_per_kwh, for the same reason: a
+      -- non-positive kWh denominator yields a EUR/kWh that does not exist.
+      CASE
+        WHEN s.gross_dropped_kwh <= 0 THEN NULL
+        ELSE round(s.gross_cost / s.gross_dropped_kwh, 4)
+      END AS gross_cost_per_kwh
+  ) g
 WHERE
   -- The per-car seed (ref_id = -car_id) is a modelling artefact that gives the
   -- pack its opening balance; it is not a charge that happened. Anything