Merge pull request #10 from Flowm/claude/sharp-pare-fa727d

feat(training): trained-weights overview with per-fit reach

Author: Flowm

CONTEXT.md

@@ -134,6 +134,19 @@ A coarse lead-hour bucket (0–48 h / 48–96 h / 96–168 h) the scorecard scor
 **Coverage**:
 The hours a model actually returned data for within the window — a runtime fact (retention varies per model and run date). Sub-full-coverage models are flagged `*` and still ranked; their empty lead bands show the gap. Distinct from **Available models**, which is the binary did-it-return-anything set.
 
+### Training
+
+**Trained weights**:
+Per-model weight **multipliers** fitted on top of the heuristic weighting from a location's stored verification sample (ADR 0007), persisted on-device and applied to the aggregate only when the user opts in via the settings toggle. A multiplier of 1 leaves the heuristic unchanged. **Training** is the act of fitting; **trained weights** are the stored result. The per-model scorecard scores these as the **Aggregate (tuned)** row.
+_Avoid_: _training weights_ (blurs the act and the result); _tuned weights_ as a separate concept (it is the same thing — "tuned" survives only in the scorecard's **Aggregate (tuned)** row label).
+
+**Training location**:
+The gridded location whose stored sample a fit was computed from — and the center of any **reach**. The training page is scoped to one training location at a time; the trained-weights overview at the bottom lists every training location stored on the device.
+
+**Reach** (or **reach radius**):
+The distance around a **training location** within which its **trained weights** also apply to other locations. Uniform within the radius, hard cutoff at the edge — no distance falloff. The default is _this point only_ (no reach: the weights apply solely to the training location's own grid cell). Resolution precedence when several sources could apply: a location's own exact-cell fit always wins; otherwise the nearest training location whose reach covers the point.
+_Avoid_: **coverage** (taken — it means temporal data availability, see "Coverage") and **region** (taken — a model's structural-advantage box, see "Home region") for this spatial concept; reserve **reach** for it.
+
 ## Flagged ambiguities
 
 **"Predictability" / "probability" / "agreement".**

src/analysis/learnedWeightsStore.test.ts

@@ -1,14 +1,19 @@
 import { describe, it, expect, beforeEach } from "vitest";
 
-import { clearWeights, loadWeights, saveWeights } from "./learnedWeightsStore";
+import { clearWeights, clearWeightsByKey, listWeights, loadWeights, saveWeights, setReach } from "./learnedWeightsStore";
+import { sampleKey } from "./sampleStore";
+
+const INNSBRUCK = { lat: 47.2654, lon: 11.3927 };
+// ~33 km north of Innsbruck — a different 0.25° cell.
+const NEARBY = { lat: 47.5654, lon: 11.3927 };
 
 describe("learnedWeightsStore", () => {
   beforeEach(() => localStorage.clear());
 
   it("round-trips weights, keyed by the 0.25° grid cell", () => {
     saveWeights(48.12, 11.38, { multipliers: { ecmwf_ifs: 1.5 }, trainedAt: "2026-06-01T00:00:00Z", improvement: 2.3 });
     expect(loadWeights(48.12, 11.38)?.multipliers.ecmwf_ifs).toBe(1.5);
-    // A nearby point resolves to the same stored weights.
+    // A nearby point in the same cell resolves to the same stored weights.
     expect(loadWeights(48.0, 11.49)?.multipliers.ecmwf_ifs).toBe(1.5);
   });
 
@@ -21,4 +26,66 @@ describe("learnedWeightsStore", () => {
     clearWeights(10, 10);
     expect(loadWeights(10, 10)).toBeNull();
   });
+
+  describe("reach", () => {
+    const store = (loc: { lat: number; lon: number }, radiusKm: number, mult: Record<string, number>): void =>
+      saveWeights(loc.lat, loc.lon, {
+        multipliers: mult,
+        trainedAt: "2026-06-01T00:00:00Z",
+        improvement: 1,
+        location: { name: "x", latitude: loc.lat, longitude: loc.lon },
+        radiusKm,
+      });
+
+    it("does not reach a different cell when radius is 0 (this point only)", () => {
+      store(INNSBRUCK, 0, { ecmwf_ifs: 1.4 });
+      expect(loadWeights(NEARBY.lat, NEARBY.lon)).toBeNull();
+    });
+
+    it("reaches a different cell within the radius", () => {
+      store(INNSBRUCK, 50, { ecmwf_ifs: 1.4 });
+      expect(loadWeights(NEARBY.lat, NEARBY.lon)?.multipliers.ecmwf_ifs).toBe(1.4);
+    });
+
+    it("does not reach beyond the radius", () => {
+      store(INNSBRUCK, 25, { ecmwf_ifs: 1.4 });
+      expect(loadWeights(NEARBY.lat, NEARBY.lon)).toBeNull();
+    });
+
+    it("prefers an exact-cell fit over a covering neighbour", () => {
+      store(INNSBRUCK, 100, { ecmwf_ifs: 1.1 });
+      store(NEARBY, 0, { ecmwf_ifs: 1.9 });
+      expect(loadWeights(NEARBY.lat, NEARBY.lon)?.multipliers.ecmwf_ifs).toBe(1.9);
+    });
+
+    it("picks the nearest covering center when several reach the point", () => {
+      // Far center reaches with a big radius; near center reaches too — near wins.
+      store({ lat: 48.0654, lon: 11.3927 }, 250, { ecmwf_ifs: 0.5 }); // ~89 km away
+      store({ lat: 47.4654, lon: 11.3927 }, 250, { ecmwf_ifs: 1.7 }); // ~22 km away
+      expect(loadWeights(INNSBRUCK.lat, INNSBRUCK.lon)?.multipliers.ecmwf_ifs).toBe(1.7);
+    });
+  });
+
+  describe("management", () => {
+    it("lists every stored entry with its grid key", () => {
+      saveWeights(INNSBRUCK.lat, INNSBRUCK.lon, { multipliers: {}, trainedAt: "t", improvement: 0 });
+      saveWeights(10, 10, { multipliers: {}, trainedAt: "t", improvement: 0 });
+      const keys = listWeights()
+        .map((e) => e.key)
+        .toSorted();
+      expect(keys).toEqual([sampleKey(10, 10), sampleKey(INNSBRUCK.lat, INNSBRUCK.lon)].toSorted());
+    });
+
+    it("updates only the reach radius via setReach", () => {
+      saveWeights(INNSBRUCK.lat, INNSBRUCK.lon, { multipliers: { ecmwf_ifs: 1.4 }, trainedAt: "t", improvement: 0 });
+      setReach(sampleKey(INNSBRUCK.lat, INNSBRUCK.lon), 50);
+      expect(loadWeights(NEARBY.lat, NEARBY.lon)?.multipliers.ecmwf_ifs).toBe(1.4);
+    });
+
+    it("clears an entry by key", () => {
+      saveWeights(INNSBRUCK.lat, INNSBRUCK.lon, { multipliers: {}, trainedAt: "t", improvement: 0 });
+      clearWeightsByKey(sampleKey(INNSBRUCK.lat, INNSBRUCK.lon));
+      expect(listWeights()).toHaveLength(0);
+    });
+  });
 });

src/analysis/learnedWeightsStore.ts

@@ -2,22 +2,44 @@
 // by the same 0.25° grid as gathered samples. Payloads are tiny (one number per
 // model), so localStorage suits better than IndexedDB. The live forecast applies
 // these only when the user opts in via the settings toggle.
+//
+// A stored fit can declare a *reach* radius (km): the area around its training
+// location within which the same weights apply to other locations (uniform, hard
+// cutoff). loadWeights resolves the exact grid cell first; failing that, it falls
+// back to the nearest training location whose reach covers the point. See ADR
+// 0007 and the "Reach" / "Training location" glossary entries in CONTEXT.md.
+
+import { haversineKm } from "@/domain/geo";
 
 import { sampleKey } from "./sampleStore";
 
 const PREFIX = "meteocompare:weights:";
 
+/** Reach radii offered in the UI (km). 0 = "this point only" (no reach). */
+export const REACH_PRESETS_KM = [0, 25, 50, 100, 250] as const;
+
 export interface StoredWeights {
   multipliers: Record<string, number>;
   /** ISO timestamp when fitted (passed in by the caller). */
   trainedAt: string;
   /** Out-of-sample validation improvement at fit time (composite delta). */
   improvement: number;
+  /** Training location — the center of any reach, and the overview's label.
+   *  Absent on entries stored before reach existed. */
+  location?: { name: string; detail?: string; latitude: number; longitude: number };
+  /** Reach radius in km: these weights apply to any location within this distance
+   *  of the training location. Absent / 0 = "this point only" (the exact cell). */
+  radiusKm?: number;
 }
 
-export function loadWeights(lat: number, lon: number): StoredWeights | null {
-  if (typeof localStorage === "undefined") return null;
-  const raw = localStorage.getItem(PREFIX + sampleKey(lat, lon));
+/** A stored entry paired with its grid key, for the device-wide overview. */
+export interface WeightEntry {
+  /** The 0.25° grid key, e.g. "47.25,11.50". */
+  key: string;
+  weights: StoredWeights;
+}
+
+function parse(raw: string | null): StoredWeights | null {
   if (!raw) return null;
   try {
     return JSON.parse(raw) as StoredWeights;
@@ -26,12 +48,69 @@ export function loadWeights(lat: number, lon: number): StoredWeights | null {
   }
 }
 
+/** The training center to measure reach from: the stored exact coords when
+ *  present, else the grid-cell center parsed back from the key. */
+function centerOf(entry: WeightEntry): { lat: number; lon: number } {
+  const loc = entry.weights.location;
+  if (loc) return { lat: loc.latitude, lon: loc.longitude };
+  const [latStr = "", lonStr = ""] = entry.key.split(",");
+  return { lat: Number(latStr), lon: Number(lonStr) };
+}
+
+/** Resolve trained weights for a location: the exact grid cell wins; otherwise
+ *  the nearest training location whose reach covers the point. null when none. */
+export function loadWeights(lat: number, lon: number): StoredWeights | null {
+  if (typeof localStorage === "undefined") return null;
+  const exact = parse(localStorage.getItem(PREFIX + sampleKey(lat, lon)));
+  if (exact) return exact;
+
+  let best: StoredWeights | null = null;
+  let bestDist = Infinity;
+  for (const entry of listWeights()) {
+    const reach = entry.weights.radiusKm ?? 0;
+    if (reach <= 0) continue;
+    const c = centerOf(entry);
+    const dist = haversineKm(lat, lon, c.lat, c.lon);
+    if (dist <= reach && dist < bestDist) {
+      bestDist = dist;
+      best = entry.weights;
+    }
+  }
+  return best;
+}
+
+/** Every stored weight set on this device, paired with its grid key. */
+export function listWeights(): WeightEntry[] {
+  if (typeof localStorage === "undefined") return [];
+  const out: WeightEntry[] = [];
+  for (let i = 0; i < localStorage.length; i++) {
+    const k = localStorage.key(i);
+    if (!k?.startsWith(PREFIX)) continue;
+    const weights = parse(localStorage.getItem(k));
+    if (weights) out.push({ key: k.slice(PREFIX.length), weights });
+  }
+  return out;
+}
+
 export function saveWeights(lat: number, lon: number, weights: StoredWeights): void {
   if (typeof localStorage === "undefined") return;
   localStorage.setItem(PREFIX + sampleKey(lat, lon), JSON.stringify(weights));
 }
 
+/** Update only the reach radius of an existing entry (by grid key). No-op when
+ *  the entry is gone. */
+export function setReach(key: string, radiusKm: number): void {
+  if (typeof localStorage === "undefined") return;
+  const weights = parse(localStorage.getItem(PREFIX + key));
+  if (!weights) return;
+  localStorage.setItem(PREFIX + key, JSON.stringify({ ...weights, radiusKm }));
+}
+
 export function clearWeights(lat: number, lon: number): void {
+  clearWeightsByKey(sampleKey(lat, lon));
+}
+
+export function clearWeightsByKey(key: string): void {
   if (typeof localStorage === "undefined") return;
-  localStorage.removeItem(PREFIX + sampleKey(lat, lon));
+  localStorage.removeItem(PREFIX + key);
 }

src/domain/geo.test.ts

@@ -0,0 +1,22 @@
+import { describe, it, expect } from "vitest";
+
+import { haversineKm } from "./geo";
+
+describe("haversineKm", () => {
+  it("is zero for identical points", () => {
+    expect(haversineKm(47.2654, 11.3927, 47.2654, 11.3927)).toBe(0);
+  });
+
+  it("matches one degree of latitude (~111 km)", () => {
+    expect(haversineKm(0, 0, 1, 0)).toBeCloseTo(111.19, 1);
+  });
+
+  it("shrinks a degree of longitude toward the poles", () => {
+    // ~74 km at 48°N, not the ~111 km it spans at the equator.
+    expect(haversineKm(48, 11, 48, 12)).toBeCloseTo(74.3, 0);
+  });
+
+  it("is symmetric", () => {
+    expect(haversineKm(47, 11, 48, 12)).toBeCloseTo(haversineKm(48, 12, 47, 11), 6);
+  });
+});

src/domain/geo.ts

@@ -0,0 +1,12 @@
+// Tiny geographic helpers. Pure and unit-tested.
+
+const EARTH_RADIUS_KM = 6371;
+const toRad = (deg: number): number => (deg * Math.PI) / 180;
+
+/** Great-circle distance between two lat/lon points, in kilometres. */
+export function haversineKm(lat1: number, lon1: number, lat2: number, lon2: number): number {
+  const dLat = toRad(lat2 - lat1);
+  const dLon = toRad(lon2 - lon1);
+  const a = Math.sin(dLat / 2) ** 2 + Math.cos(toRad(lat1)) * Math.cos(toRad(lat2)) * Math.sin(dLon / 2) ** 2;
+  return 2 * EARTH_RADIUS_KM * Math.asin(Math.min(1, Math.sqrt(a)));
+}