Update app.py

app.py

@@ -1,10 +1,18 @@
-
 # ===============================================================
 # Rendered Frame Theory — Live Prediction Console (Open Method)
 # Domains: Atmospheric / Seismic / Magnetic / Solar
+# Adds: Verifiable "Forecast Receipt" export + Receipt Upload Verification
 # ===============================================================
 
 import math
+import os
+import sys
+import json
+import uuid
+import base64
+import hashlib
+import platform
+from typing import Optional, Dict, Any, List, Tuple
 from datetime import datetime, timezone, timedelta
 
 import gradio as gr
@@ -13,8 +21,10 @@ import numpy as np
 import pandas as pd
 
 APP_NAME = "Rendered Frame Theory — Live Prediction Console (Open Method)"
+APP_VERSION = "v1.1-receipts+verify"
 UA = {"User-Agent": "RFTSystems/LivePredictionConsole"}
 
+# ---------- Constants --------------------------------------------------------
 T_EARTH = 365.2422 * 24 * 3600.0
 OMEGA_OBS = 2.0 * math.pi / T_EARTH
 K_TAU = 1.38
@@ -33,8 +43,13 @@ RING_OF_FIRE_BBOXES = [
 ]
 
 
+# ---------- Core Helpers -----------------------------------------------------
+def utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
 def utc_now_iso() -> str:
-    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+    return utc_now().isoformat().replace("+00:00", "Z")
 
 
 def clamp(x: float, a: float, b: float) -> float:
@@ -56,15 +71,124 @@ def index_from_tau(tau: float) -> float:
     return float(OMEGA_OBS * float(tau) * ALPHA_R)
 
 
-def geocode_location(q: str):
+def sha256_hex(b: bytes) -> str:
+    return hashlib.sha256(b).hexdigest()
+
+
+def safe_json_dumps(obj: Any) -> str:
+    return json.dumps(obj, ensure_ascii=False, indent=2, sort_keys=True, default=str)
+
+
+def env_snapshot() -> Dict[str, Any]:
+    return {
+        "app_name": APP_NAME,
+        "app_version": APP_VERSION,
+        "python": sys.version,
+        "platform": platform.platform(),
+        "packages": {
+            "gradio": getattr(gr, "__version__", "unknown"),
+            "httpx": getattr(httpx, "__version__", "unknown"),
+            "numpy": getattr(np, "__version__", "unknown"),
+            "pandas": getattr(pd, "__version__", "unknown"),
+        },
+        "constants": {
+            "T_EARTH": T_EARTH,
+            "OMEGA_OBS": OMEGA_OBS,
+            "K_TAU": K_TAU,
+            "ALPHA_R": ALPHA_R,
+        },
+        # Optional: set as HF Space secret if you want deterministic provenance for code versioning
+        "git_commit": os.environ.get("RFT_GIT_COMMIT", ""),
+    }
+
+
+# ---------- Provenance / Fetch Logging --------------------------------------
+def record_fetch(
+    prov_list: List[Dict[str, Any]],
+    name: str,
+    url: str,
+    params: Optional[Dict[str, Any]],
+    status_code: Optional[int],
+    content_type: Optional[str],
+    body_bytes: Optional[bytes],
+    include_raw_payloads: bool,
+    fetched_at_utc: str,
+    error: Optional[str] = None,
+    request_url: Optional[str] = None,
+) -> None:
+    body_bytes = body_bytes or b""
+    item: Dict[str, Any] = {
+        "name": name,
+        "fetched_at_utc": fetched_at_utc,
+        "url": url,
+        "params": params or {},
+        "request_url": request_url or "",
+        "status_code": status_code,
+        "content_type": content_type or "",
+        "bytes_len": int(len(body_bytes)),
+        "sha256": sha256_hex(body_bytes) if body_bytes else "",
+        "error": error or "",
+    }
+    if include_raw_payloads and body_bytes:
+        item["raw_b64"] = base64.b64encode(body_bytes).decode("ascii")
+        item["raw_encoding"] = "base64"
+    prov_list.append(item)
+
+
+def http_get_json(
+    name: str,
+    url: str,
+    params: Optional[Dict[str, Any]],
+    prov_list: List[Dict[str, Any]],
+    include_raw_payloads: bool,
+    timeout: float,
+) -> Any:
+    fetched_at = utc_now_iso()
+    try:
+        r = httpx.get(url, params=params, headers=UA, timeout=timeout)
+        body = r.content
+        ct = r.headers.get("content-type", "")
+        req_url = str(r.request.url) if r.request else ""
+        record_fetch(
+            prov_list=prov_list,
+            name=name,
+            url=url,
+            params=params,
+            status_code=r.status_code,
+            content_type=ct,
+            body_bytes=body,
+            include_raw_payloads=include_raw_payloads,
+            fetched_at_utc=fetched_at,
+            error=None,
+            request_url=req_url,
+        )
+        r.raise_for_status()
+        return r.json()
+    except Exception as e:
+        record_fetch(
+            prov_list=prov_list,
+            name=name,
+            url=url,
+            params=params,
+            status_code=None,
+            content_type=None,
+            body_bytes=None,
+            include_raw_payloads=include_raw_payloads,
+            fetched_at_utc=fetched_at,
+            error=str(e),
+            request_url=None,
+        )
+        raise
+
+
+# ---------- Data Adapters ----------------------------------------------------
+def geocode_location(q: str, prov_list: List[Dict[str, Any]], include_raw_payloads: bool):
     q = (q or "").strip()
     if not q:
         return None, None, "Empty location"
     url = "https://geocoding-api.open-meteo.com/v1/search"
     params = {"name": q, "count": 1, "language": "en", "format": "json"}
-    r = httpx.get(url, params=params, headers=UA, timeout=12)
-    r.raise_for_status()
-    js = r.json()
+    js = http_get_json("GEOCODE_OPENMETEO", url, params, prov_list, include_raw_payloads, timeout=12)
     results = js.get("results") or []
     if not results:
         return None, None, f"Could not geocode '{q}'"
@@ -75,7 +199,7 @@ def geocode_location(q: str):
     return lat, lon, display
 
 
-def fetch_openmeteo_hourly(lat: float, lon: float, past_days: int = 1):
+def fetch_openmeteo_hourly(lat: float, lon: float, prov_list: List[Dict[str, Any]], include_raw_payloads: bool, past_days: int = 1):
     url = "https://api.open-meteo.com/v1/forecast"
     params = {
         "latitude": lat,
@@ -85,9 +209,7 @@ def fetch_openmeteo_hourly(lat: float, lon: float, past_days: int = 1):
         "forecast_days": 1,
         "timezone": "UTC",
     }
-    r = httpx.get(url, params=params, headers=UA, timeout=18)
-    r.raise_for_status()
-    js = r.json()
+    js = http_get_json("OPENMETEO_HOURLY", url, params, prov_list, include_raw_payloads, timeout=18)
     hourly = js.get("hourly") or {}
     return {
         "time": hourly.get("time") or [],
@@ -95,14 +217,13 @@ def fetch_openmeteo_hourly(lat: float, lon: float, past_days: int = 1):
         "rh": hourly.get("relative_humidity_2m") or [],
         "p": hourly.get("pressure_msl") or [],
         "wind": hourly.get("wind_speed_10m") or [],
+        "meta": {"source": "Open-Meteo", "url": url, "params": params},
     }
 
 
-def fetch_kp_last_24h():
+def fetch_kp_last_24h(prov_list: List[Dict[str, Any]], include_raw_payloads: bool):
     url = "https://services.swpc.noaa.gov/json/planetary_k_index_1m.json"
-    r = httpx.get(url, headers=UA, timeout=15)
-    r.raise_for_status()
-    js = r.json()
+    js = http_get_json("NOAA_SWPC_KP_1M", url, None, prov_list, include_raw_payloads, timeout=15)
     if not isinstance(js, list) or not js:
         return []
     vals = []
@@ -117,11 +238,9 @@ def fetch_kp_last_24h():
     return vals[-1440:]
 
 
-def fetch_goes_xray_1day():
+def fetch_goes_xray_1day(prov_list: List[Dict[str, Any]], include_raw_payloads: bool):
     url = "https://services.swpc.noaa.gov/json/goes/primary/xrays-1-day.json"
-    r = httpx.get(url, headers=UA, timeout=15)
-    r.raise_for_status()
-    js = r.json()
+    js = http_get_json("NOAA_SWPC_GOES_XRAY_1D", url, None, prov_list, include_raw_payloads, timeout=15)
     if not isinstance(js, list) or not js:
         return []
     out = []
@@ -136,14 +255,25 @@ def fetch_goes_xray_1day():
     return out
 
 
-def fetch_usgs_quakes(hours: int, minmag: float, bbox=None, center=None, radius_km=None):
+def fetch_usgs_quakes(
+    hours: int,
+    minmag: float,
+    prov_list: List[Dict[str, Any]],
+    include_raw_payloads: bool,
+    bbox: Optional[Tuple[float, float, float, float]] = None,
+    center: Optional[Tuple[float, float]] = None,
+    radius_km: Optional[float] = None,
+) -> Dict[str, Any]:
     url = "https://earthquake.usgs.gov/fdsnws/event/1/query"
-    end = datetime.now(timezone.utc)
+    end = utc_now()
     start = end - timedelta(hours=int(hours))
-    params = {
+    start_iso = start.isoformat().replace("+00:00", "Z")
+    end_iso = end.isoformat().replace("+00:00", "Z")
+
+    params: Dict[str, Any] = {
         "format": "geojson",
-        "starttime": start.isoformat().replace("+00:00", "Z"),
-        "endtime": end.isoformat().replace("+00:00", "Z"),
+        "starttime": start_iso,
+        "endtime": end_iso,
         "minmagnitude": str(float(minmag)),
         "orderby": "time",
     }
@@ -169,12 +299,11 @@ def fetch_usgs_quakes(hours: int, minmag: float, bbox=None, center=None, radius_
             }
         )
 
-    r = httpx.get(url, params=params, headers=UA, timeout=22)
-    r.raise_for_status()
-    js = r.json()
+    js = http_get_json("USGS_FDSN_EVENTS", url, params, prov_list, include_raw_payloads, timeout=22)
     feats = js.get("features") if isinstance(js, dict) else None
     if not feats:
-        return []
+        return {"events": [], "start": start_iso, "end": end_iso, "url": url, "params": params}
+
     out = []
     for f in feats:
         props = f.get("properties") or {}
@@ -186,10 +315,18 @@ def fetch_usgs_quakes(hours: int, minmag: float, bbox=None, center=None, radius_
                 "time": props.get("time"),
             }
         )
-    return out
-
-
-def build_verification_links(lat: float, lon: float, seismic_mode: str, seismic_region: str, radius_km: float) -> str:
+    return {"events": out, "start": start_iso, "end": end_iso, "url": url, "params": params}
+
+
+# ---------- Verification Links (user-facing) --------------------------------
+def build_verification_links(
+    lat: float,
+    lon: float,
+    seismic_mode: str,
+    seismic_region: str,
+    radius_km: float,
+    usgs_meta: Optional[Dict[str, Any]],
+) -> str:
     swpc_kp_page = "https://www.swpc.noaa.gov/products/planetary-k-index"
     swpc_kp_json = "https://services.swpc.noaa.gov/json/planetary_k_index_1m.json"
 
@@ -203,16 +340,26 @@ def build_verification_links(lat: float, lon: float, seismic_mode: str, seismic_
     )
 
     usgs_map = "https://earthquake.usgs.gov/earthquakes/map/"
-    if seismic_mode == "Local radius":
-        usgs_query = (
-            "https://earthquake.usgs.gov/fdsnws/event/1/query"
-            f"?format=geojson&starttime=&endtime=&minmagnitude=2.5"
-            f"&latitude={lat:.5f}&longitude={lon:.5f}&maxradiuskm={float(radius_km):.0f}"
-        )
-        scope = f"Local radius query ({int(radius_km)} km around your location)"
-    else:
-        scope = f"Region mode ({seismic_region})"
-        usgs_query = "https://earthquake.usgs.gov/fdsnws/event/1/query?format=geojson&starttime=&endtime=&minmagnitude=2.5"
+    scope = "Unknown"
+    usgs_query = "https://earthquake.usgs.gov/fdsnws/event/1/query?format=geojson"
+
+    def build_q(meta: Dict[str, Any]) -> str:
+        base = meta.get("url", "https://earthquake.usgs.gov/fdsnws/event/1/query")
+        params = meta.get("params", {})
+        pairs = [f"{k}={v}" for k, v in params.items()]
+        return base + "?" + "&".join(pairs)
+
+    if usgs_meta:
+        # RingOfFire can be multi-request
+        if "requests" in usgs_meta and isinstance(usgs_meta["requests"], list) and usgs_meta["requests"]:
+            usgs_query = build_q(usgs_meta["requests"][0])
+            scope = f"Multi-request (RingOfFire): showing first of {len(usgs_meta['requests'])}"
+        else:
+            usgs_query = build_q(usgs_meta)
+            if seismic_mode == "Local radius":
+                scope = f"Local radius query ({int(radius_km)} km around your location)"
+            else:
+                scope = f"Region mode ({seismic_region})"
 
     return (
         "### Verify instantly (official sources)\n"
@@ -227,8 +374,9 @@ def build_verification_links(lat: float, lon: float, seismic_mode: str, seismic_
     )
 
 
-def magnetic_agent():
-    kp = fetch_kp_last_24h()
+# ---------- Agents -----------------------------------------------------------
+def magnetic_agent(prov_list: List[Dict[str, Any]], include_raw_payloads: bool) -> Dict[str, Any]:
+    kp = fetch_kp_last_24h(prov_list, include_raw_payloads)
     if len(kp) < 30:
         return {"enabled": False, "reason": "NOAA Kp feed too short"}
     last = float(kp[-1])
@@ -273,8 +421,8 @@ def magnetic_agent():
     }
 
 
-def solar_agent():
-    flux = fetch_goes_xray_1day()
+def solar_agent(prov_list: List[Dict[str, Any]], include_raw_payloads: bool) -> Dict[str, Any]:
+    flux = fetch_goes_xray_1day(prov_list, include_raw_payloads)
     if len(flux) < 50:
         return {"enabled": False, "reason": "GOES X-ray feed too short"}
     tail = flux[-120:] if len(flux) >= 120 else flux[-60:]
@@ -319,8 +467,8 @@ def solar_agent():
     }
 
 
-def atmospheric_agent(lat: float, lon: float, display: str):
-    wx = fetch_openmeteo_hourly(lat, lon, past_days=1)
+def atmospheric_agent(lat: float, lon: float, display: str, prov_list: List[Dict[str, Any]], include_raw_payloads: bool) -> Dict[str, Any]:
+    wx = fetch_openmeteo_hourly(lat, lon, prov_list, include_raw_payloads, past_days=1)
     temp = wx["temp"]
     p = wx["p"]
     wind = wx["wind"]
@@ -386,29 +534,34 @@ def atmospheric_agent(lat: float, lon: float, display: str):
     }
 
 
-def seismic_agent_region(region: str):
+def seismic_agent_region(region: str, prov_list: List[Dict[str, Any]], include_raw_payloads: bool):
     if region == "RingOfFire":
         seen = set()
         eqs = []
+        metas = []
         for bb in RING_OF_FIRE_BBOXES:
-            chunk = fetch_usgs_quakes(hours=24, minmag=2.5, bbox=bb)
-            for e in chunk:
+            res = fetch_usgs_quakes(hours=24, minmag=2.5, bbox=bb, prov_list=prov_list, include_raw_payloads=include_raw_payloads)
+            metas.append({"url": res["url"], "params": res["params"], "start": res["start"], "end": res["end"]})
+            for e in res["events"]:
                 eid = e.get("id")
                 if eid and eid not in seen:
                     seen.add(eid)
                     eqs.append(e)
+        meta = {"mode": "RingOfFireMultiBBox", "requests": metas}
     else:
         bbox = REGION_BBOX.get(region, None)
-        eqs = fetch_usgs_quakes(hours=24, minmag=2.5, bbox=bbox)
-    return eqs, f"Region={region}"
+        res = fetch_usgs_quakes(hours=24, minmag=2.5, bbox=bbox, prov_list=prov_list, include_raw_payloads=include_raw_payloads)
+        eqs = res["events"]
+        meta = {"url": res["url"], "params": res["params"], "start": res["start"], "end": res["end"]}
+    return eqs, f"Region={region}", meta
 
 
-def seismic_agent_local(lat: float, lon: float, radius_km: float):
-    eqs = fetch_usgs_quakes(hours=24, minmag=2.5, center=(lat, lon), radius_km=radius_km)
-    return eqs, f"Local radius={int(radius_km)}km"
+def seismic_agent_local(lat: float, lon: float, radius_km: float, prov_list: List[Dict[str, Any]], include_raw_payloads: bool):
+    res = fetch_usgs_quakes(hours=24, minmag=2.5, center=(lat, lon), radius_km=radius_km, prov_list=prov_list, include_raw_payloads=include_raw_payloads)
+    return res["events"], f"Local radius={int(radius_km)}km", {"url": res["url"], "params": res["params"], "start": res["start"], "end": res["end"]}
 
 
-def seismic_score(eqs):
+def seismic_score(eqs: List[Dict[str, Any]]):
     N = int(len(eqs))
     mags = []
     for e in eqs:
@@ -443,15 +596,15 @@ def seismic_score(eqs):
     return pred, rule, z, tau, idx, N, Mmax
 
 
-def seismic_agent(mode: str, region: str, lat: float, lon: float, radius_km: float):
+def seismic_agent(mode: str, region: str, lat: float, lon: float, radius_km: float, prov_list: List[Dict[str, Any]], include_raw_payloads: bool) -> Dict[str, Any]:
     if mode == "Local radius":
-        eqs, scope = seismic_agent_local(lat, lon, radius_km)
+        eqs, scope, usgs_meta = seismic_agent_local(lat, lon, radius_km, prov_list, include_raw_payloads)
         location_effect = "Location changes Seismic in Local radius mode."
         do = "Use to monitor seismic activity within the selected radius around your typed location."
         dont = "Do not treat as time/epicenter prediction."
         truth_scope = f"USGS events within {int(radius_km)} km"
     else:
-        eqs, scope = seismic_agent_region(region)
+        eqs, scope, usgs_meta = seismic_agent_region(region, prov_list, include_raw_payloads)
         location_effect = "Location does not change Seismic in Region mode. Region selector does."
         do = "Use as a regional seismic stress monitor."
         dont = "Do not treat as time/epicenter prediction."
@@ -472,50 +625,130 @@ def seismic_agent(mode: str, region: str, lat: float, lon: float, radius_km: flo
         "index": float(idx),
         "live_status": live,
         "truth_source": f"USGS FDSN event feed ({truth_scope})",
-        "inputs_used": {"count_24h": N, "max_mag_24h": Mmax, "mode": mode, "region": region, "radius_km": float(radius_km), "lat": float(lat), "lon": float(lon)},
+        "inputs_used": {
+            "count_24h": N,
+            "max_mag_24h": Mmax,
+            "mode": mode,
+            "region": region,
+            "radius_km": float(radius_km),
+            "lat": float(lat),
+            "lon": float(lon),
+        },
         "location_effect": location_effect,
         "do": do,
         "dont": dont,
         "what_it_is_not": "Not an earthquake time predictor. Not a rupture location predictor.",
         "why": "z_seis compresses activity density and severity into a bounded stress coordinate; τ_eff rises as ln(1+z).",
         "how": "Fetch USGS → count + max magnitude → z_seis → τ_eff → Index → label via fixed thresholds.",
+        "usgs_meta": usgs_meta,
+    }
+
+
+# ---------- Receipt Build/Save ----------------------------------------------
+def build_receipt(
+    run_id: str,
+    run_started_utc: str,
+    run_finished_utc: str,
+    location_text: str,
+    lat: float,
+    lon: float,
+    display: str,
+    seismic_mode: str,
+    seismic_region: str,
+    radius_km: float,
+    df: pd.DataFrame,
+    atm: Dict[str, Any],
+    sei: Dict[str, Any],
+    mag: Dict[str, Any],
+    sol: Dict[str, Any],
+    prov_list: List[Dict[str, Any]],
+    include_raw_payloads: bool,
+) -> Dict[str, Any]:
+    return {
+        "receipt_version": 1,
+        "run_id": run_id,
+        "run_started_utc": run_started_utc,
+        "run_finished_utc": run_finished_utc,
+        "settings": {
+            "location_text": location_text,
+            "geocode_result": {"display": display, "lat": lat, "lon": lon},
+            "seismic_mode": seismic_mode,
+            "seismic_region": seismic_region,
+            "radius_km": float(radius_km),
+            "include_raw_payloads": bool(include_raw_payloads),
+        },
+        "outputs": {
+            "table_rows": df.to_dict(orient="records"),
+            "agents": {
+                "atmospheric": atm,
+                "seismic": sei,
+                "magnetic": mag,
+                "solar": sol,
+            },
+        },
+        "provenance": {"fetches": prov_list},
+        "environment": env_snapshot(),
+        "verification_note": (
+            "Receipt is tamper-evident via sha256 for each upstream payload. "
+            "If raw payloads are embedded (raw_b64), integrity + offline verification is strong. "
+            "If not embedded, you can still compare provider payloads later, but providers may revise feeds."
+        ),
     }
 
 
-def run_forecast(location_text: str, seismic_mode: str, seismic_region: str, radius_km: float):
+def write_receipt_to_file(receipt: Dict[str, Any]) -> str:
+    run_id = receipt.get("run_id", "run")
+    path = f"/tmp/rft_forecast_receipt_{run_id}.json"
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(safe_json_dumps(receipt))
+    return path
+
+
+# ---------- Forecast Runner --------------------------------------------------
+def run_forecast(location_text: str, seismic_mode: str, seismic_region: str, radius_km: float, include_raw_payloads: bool):
+    run_started = utc_now_iso()
+    run_id = uuid.uuid4().hex[:12]
+    prov: List[Dict[str, Any]] = []
+
+    # Geocode
     try:
-        lat, lon, display = geocode_location(location_text)
+        lat, lon, display = geocode_location(location_text, prov, include_raw_payloads)
     except Exception as e:
         df = pd.DataFrame([{"Domain": "Error", "RFT Prediction": "DISABLED", "Live Status": f"Geocode error: {e}"}])
         empty = {"enabled": False, "reason": f"Geocode error: {e}"}
-        return f"❌ Geocode error: {e}", df, "", empty, empty, empty, empty
+        receipt = build_receipt(run_id, run_started, utc_now_iso(), location_text, float("nan"), float("nan"), "", seismic_mode, seismic_region, radius_km, df, empty, empty, empty, empty, prov, include_raw_payloads)
+        receipt_path = write_receipt_to_file(receipt)
+        return f"❌ Geocode error: {e}", df, "", empty, empty, empty, empty, receipt, receipt_path
 
     if lat is None:
         df = pd.DataFrame([{"Domain": "Error", "RFT Prediction": "DISABLED", "Live Status": display}])
         empty = {"enabled": False, "reason": display}
-        return f"❌ {display}", df, "", empty, empty, empty, empty
+        receipt = build_receipt(run_id, run_started, utc_now_iso(), location_text, float("nan"), float("nan"), display, seismic_mode, seismic_region, radius_km, df, empty, empty, empty, empty, prov, include_raw_payloads)
+        receipt_path = write_receipt_to_file(receipt)
+        return f"❌ {display}", df, "", empty, empty, empty, empty, receipt, receipt_path
 
+    # Agents
     try:
-        atm = atmospheric_agent(lat, lon, display)
+        atm = atmospheric_agent(lat, lon, display, prov, include_raw_payloads)
     except Exception as e:
         atm = {"enabled": False, "reason": f"atmos error: {e}"}
 
     try:
-        sei = seismic_agent(seismic_mode, seismic_region, lat, lon, radius_km)
+        sei = seismic_agent(seismic_mode, seismic_region, lat, lon, radius_km, prov, include_raw_payloads)
     except Exception as e:
         sei = {"enabled": False, "reason": f"seismic error: {e}"}
 
     try:
-        mag = magnetic_agent()
+        mag = magnetic_agent(prov, include_raw_payloads)
     except Exception as e:
         mag = {"enabled": False, "reason": f"magnetic error: {e}"}
 
     try:
-        sol = solar_agent()
+        sol = solar_agent(prov, include_raw_payloads)
     except Exception as e:
         sol = {"enabled": False, "reason": f"solar error: {e}"}
 
-    def fmt_row(domain: str, out: dict):
+    def fmt_row(domain: str, out: Dict[str, Any]):
         if not out.get("enabled"):
             return {"Domain": domain, "RFT Prediction": "DISABLED", "Live Status": out.get("reason", "missing inputs")}
         idx = out.get("index", None)
@@ -539,13 +772,221 @@ def run_forecast(location_text: str, seismic_mode: str, seismic_region: str, rad
         ]
     )
 
-    ts = utc_now_iso()
-    header = f"**Location:** {display} (lat {lat:.3f}, lon {lon:.3f}) | **UTC:** {ts}"
+    run_finished = utc_now_iso()
+    header = f"**Location:** {display} (lat {lat:.3f}, lon {lon:.3f}) | **UTC:** {run_finished} | **Run ID:** `{run_id}`"
+
+    usgs_meta = None
+    if isinstance(sei, dict):
+        usgs_meta = sei.get("usgs_meta", None)
+
+    verify_md = build_verification_links(lat, lon, seismic_mode, seismic_region, radius_km, usgs_meta)
+
+    receipt = build_receipt(
+        run_id=run_id,
+        run_started_utc=run_started,
+        run_finished_utc=run_finished,
+        location_text=location_text,
+        lat=lat,
+        lon=lon,
+        display=display,
+        seismic_mode=seismic_mode,
+        seismic_region=seismic_region,
+        radius_km=radius_km,
+        df=df,
+        atm=atm,
+        sei=sei,
+        mag=mag,
+        sol=sol,
+        prov_list=prov,
+        include_raw_payloads=include_raw_payloads,
+    )
+    receipt_path = write_receipt_to_file(receipt)
+
+    return header, df, verify_md, atm, sei, mag, sol, receipt, receipt_path
+
+
+# ---------- Receipt Verification --------------------------------------------
+def _safe_float(x):
+    try:
+        if x is None:
+            return None
+        return float(x)
+    except Exception:
+        return None
+
 
-    verify_md = build_verification_links(lat, lon, seismic_mode, seismic_region, radius_km)
-    return header, df, verify_md, atm, sei, mag, sol
+def _close(a, b, tol=1e-9):
+    if a is None or b is None:
+        return False
+    return abs(float(a) - float(b)) <= tol * max(1.0, abs(float(a)), abs(float(b)))
 
 
+def _verify_payload_hashes(fetches: List[Dict[str, Any]]):
+    rows = []
+    ok_all = True
+    for f in (fetches or []):
+        name = f.get("name", "")
+        h = f.get("sha256", "")
+        raw_b64 = f.get("raw_b64", None)
+
+        if not raw_b64:
+            rows.append({"Check": f"payload:{name}", "Status": "SKIP", "Detail": "No raw_b64 embedded"})
+            continue
+
+        try:
+            raw = base64.b64decode(raw_b64.encode("ascii"))
+            h2 = sha256_hex(raw)
+            ok = (h2 == h)
+            ok_all = ok_all and ok
+            rows.append({"Check": f"payload:{name}", "Status": "PASS" if ok else "FAIL", "Detail": f"sha256(receipt)={h} sha256(decoded)={h2}"})
+        except Exception as e:
+            ok_all = False
+            rows.append({"Check": f"payload:{name}", "Status": "FAIL", "Detail": f"Decode/hash error: {e}"})
+
+    return ok_all, rows
+
+
+def _recompute_domain(domain: str, agent: Dict[str, Any]):
+    if not agent or not agent.get("enabled"):
+        return {"enabled": False}
+
+    iu = agent.get("inputs_used") or {}
+    dom = (domain or "").strip().lower()
+
+    if dom == "atmospheric":
+        dT = _safe_float(iu.get("dT_12h"))
+        dp = _safe_float(iu.get("dP_12h"))
+        if dT is None:
+            return {"error": "Missing inputs_used.dT_12h"}
+        z_dt = clamp(dT / 10.0, 0.0, 2.0)
+        z_dp = clamp((abs(dp) / 12.0) if dp is not None else 0.0, 0.0, 1.5)
+        z = clamp(z_dt + z_dp, 0.0, 3.0)
+        if dT >= 10.0 or (dp is not None and dp <= -10.0):
+            pred = "storm risk"
+        elif dT >= 7.0 or (dp is not None and dp <= -6.0):
+            pred = "swing"
+        elif dT >= 4.0:
+            pred = "mild swing"
+        else:
+            pred = "stable"
+
+    elif dom == "seismic":
+        N = _safe_float(iu.get("count_24h"))
+        Mmax = _safe_float(iu.get("max_mag_24h"))
+        if N is None or Mmax is None:
+            return {"error": "Missing inputs_used.count_24h or inputs_used.max_mag_24h"}
+        z_count = clamp(N / 60.0, 0.0, 1.5)
+        z_mag = clamp(max(0.0, Mmax - 4.0) / 2.5, 0.0, 1.5)
+        z = clamp(z_count + z_mag, 0.0, 3.0)
+        if Mmax >= 6.5 or z >= 2.2:
+            pred = "alert"
+        elif Mmax >= 5.5 or z >= 1.5:
+            pred = "watch"
+        elif N >= 25 or z >= 1.0:
+            pred = "monitor"
+        else:
+            pred = "quiet"
+
+    elif dom == "magnetic":
+        last = _safe_float(iu.get("kp_last"))
+        drift = _safe_float(iu.get("kp_drift"))
+        slope = _safe_float(iu.get("kp_slope"))
+        if last is None or drift is None or slope is None:
+            return {"error": "Missing inputs_used.kp_last/kp_drift/kp_slope"}
+        z = clamp((last / 9.0) + (drift / 2.0) + 2.0 * abs(slope), 0.0, 3.0)
+        if last >= 7.0 or z >= 2.0:
+            pred = "warning"
+        elif last >= 5.0 or z >= 1.2:
+            pred = "watch"
+        elif last >= 4.0 or z >= 0.8:
+            pred = "monitor"
+        else:
+            pred = "hold"
+
+    elif dom == "solar":
+        f_mean = _safe_float(iu.get("flux_mean"))
+        f_peak = _safe_float(iu.get("flux_peak"))
+        if f_mean is None or f_peak is None:
+            return {"error": "Missing inputs_used.flux_mean/flux_peak"}
+        lr = stable_log_ratio(f_mean, 1e-8)
+        z = clamp(lr / 10.0, 0.0, 3.0)
+        if f_peak >= 1e-4 or z >= 2.2:
+            pred = "flare likely"
+        elif f_peak >= 1e-5 or z >= 1.5:
+            pred = "flare watch"
+        elif f_mean >= 1e-6 or z >= 0.9:
+            pred = "monitor"
+        else:
+            pred = "hold"
+
+    else:
+        return {"error": f"Unknown domain '{domain}'"}
+
+    tau = tau_eff_from_z(z)
+    idx = index_from_tau(tau)
+    return {"z": z, "tau_eff": tau, "index": idx, "prediction": pred}
+
+
+def verify_receipt(uploaded_file):
+    if uploaded_file is None:
+        return "❌ Upload a receipt JSON first.", pd.DataFrame([])
+
+    try:
+        content = uploaded_file.read()
+        receipt = json.loads(content.decode("utf-8"))
+    except Exception as e:
+        return f"❌ Could not read JSON: {e}", pd.DataFrame([])
+
+    checks: List[Dict[str, str]] = []
+    ok = True
+
+    for key in ["run_id", "settings", "outputs", "provenance", "environment"]:
+        if key not in receipt:
+            ok = False
+            checks.append({"Check": f"has:{key}", "Status": "FAIL", "Detail": "Missing key"})
+        else:
+            checks.append({"Check": f"has:{key}", "Status": "PASS", "Detail": ""})
+
+    fetches = (receipt.get("provenance") or {}).get("fetches") or []
+    ok_payloads, rows = _verify_payload_hashes(fetches)
+    checks.extend(rows)
+    ok = ok and ok_payloads
+
+    agents = ((receipt.get("outputs") or {}).get("agents") or {})
+    mapping = {
+        "Atmospheric": agents.get("atmospheric"),
+        "Seismic": agents.get("seismic"),
+        "Magnetic": agents.get("magnetic"),
+        "Solar": agents.get("solar"),
+    }
+
+    for dom, agent in mapping.items():
+        if not agent or not agent.get("enabled"):
+            checks.append({"Check": f"recompute:{dom}", "Status": "SKIP", "Detail": "Agent disabled"})
+            continue
+
+        rec = _recompute_domain(dom, agent)
+        if rec.get("error"):
+            ok = False
+            checks.append({"Check": f"recompute:{dom}", "Status": "FAIL", "Detail": rec["error"]})
+            continue
+
+        z_ok = _close(rec["z"], agent.get("z"), tol=1e-6)
+        t_ok = _close(rec["tau_eff"], agent.get("tau_eff"), tol=1e-6)
+        i_ok = _close(rec["index"], agent.get("index"), tol=1e-6)
+        p_ok = (str(rec["prediction"]).strip().lower() == str(agent.get("prediction")).strip().lower())
+
+        ok = ok and z_ok and t_ok and i_ok and p_ok
+        checks.append({"Check": f"{dom}:z", "Status": "PASS" if z_ok else "FAIL", "Detail": f"expected={agent.get('z')} recomputed={rec['z']}"})
+        checks.append({"Check": f"{dom}:tau", "Status": "PASS" if t_ok else "FAIL", "Detail": f"expected={agent.get('tau_eff')} recomputed={rec['tau_eff']}"})
+        checks.append({"Check": f"{dom}:index", "Status": "PASS" if i_ok else "FAIL", "Detail": f"expected={agent.get('index')} recomputed={rec['index']}"})
+        checks.append({"Check": f"{dom}:label", "Status": "PASS" if p_ok else "FAIL", "Detail": f"expected={agent.get('prediction')} recomputed={rec['prediction']}"})
+
+    status = "✅ Receipt verification PASS" if ok else "⚠️ Receipt verification FAIL (see checks)"
+    return status, pd.DataFrame(checks)
+
+
+# ---------- Markdown Tabs ----------------------------------------------------
 INSTRUCTIONS_MD = """
 ## Use and interpretation
 
@@ -561,11 +1002,15 @@ INSTRUCTIONS_MD = """
 **Run Forecast**
 - Pulls live data and recomputes from scratch.
 - No auto-refresh. No memory. No smoothing.
-
-**Reading the table**
-- RFT Prediction shows model state + index + z + τ_eff.
-- Live Status shows the raw physical measurements used.
-- DISABLED means missing/insufficient live data; no guessing is performed.
+- No guessing when data is missing (DISABLED instead).
+
+**Forecast Receipts**
+- Each run generates a downloadable receipt JSON that includes:
+  - source URLs + params + timestamps
+  - sha256 hashes of upstream payloads
+  - computed intermediates + label rule fired
+  - environment snapshot (versions + constants)
+- Optional: embed raw upstream payloads for stronger offline verification.
 """
 
 METHOD_MD = f"""
@@ -587,53 +1032,33 @@ Decision thresholds are shown per-domain in the agent output as `rule_fired`.
 """
 
 
+# ---------- UI ---------------------------------------------------------------
 with gr.Blocks(title=APP_NAME) as demo:
     gr.Markdown(f"# {APP_NAME}")
+    gr.Markdown(f"**Build:** `{APP_VERSION}`")
 
     with gr.Tab("Live Forecast"):
         loc = gr.Textbox(label="Location", value="London")
-        gr.Markdown(
-            "**Location input**\n\n"
-            "- Used for Atmospheric.\n"
-            "- Used for Seismic only in **Local radius** mode.\n"
-            "- Not used for Solar or Magnetic (global signals).\n\n"
-            "If a location cannot be resolved, predictions are disabled instead of guessed."
-        )
 
         seismic_mode = gr.Radio(
             choices=["Region", "Local radius"],
             value="Local radius",
             label="Seismic Mode"
         )
-        gr.Markdown(
-            "**Seismic Mode**\n\n"
-            "- **Region:** counts earthquakes in a large region.\n"
-            "- **Local radius:** counts earthquakes within a radius (km) around your typed location.\n\n"
-            "This is a stress monitor, not a time/epicenter prediction system."
-        )
 
         with gr.Row():
             region = gr.Dropdown(["Global", "EMEA", "AMER", "APAC", "RingOfFire"], value="EMEA", label="Seismic Region (used in Region mode)")
             radius = gr.Slider(50, 2000, value=500, step=50, label="Seismic Radius km (used in Local radius mode)")
 
-        btn = gr.Button("Run Forecast", variant="primary")
-        gr.Markdown(
-            "**Run Forecast**\n\n"
-            "- Pulls live data and recomputes from scratch.\n"
-            "- No auto-refresh.\n"
-            "- No stored memory.\n"
-            "- No guessing when data is missing."
+        include_raw = gr.Checkbox(
+            value=False,
+            label="Receipt durability: embed raw upstream payloads (larger download, stronger verification)"
         )
 
+        btn = gr.Button("Run Forecast", variant="primary")
+
         header_md = gr.Markdown()
-        gr.Markdown(
-            "**How to read the table**\n\n"
-            "- RFT Prediction shows model state + index + z + τ_eff.\n"
-            "- Live Status shows the raw physical measurements used.\n"
-            "- DISABLED means missing/insufficient live data; no guessing is performed."
-        )
         table = gr.Dataframe(headers=["Domain", "RFT Prediction", "Live Status"], interactive=False)
-
         verify_md = gr.Markdown()
 
         with gr.Accordion("Atmospheric details", open=False):
@@ -645,11 +1070,33 @@ with gr.Blocks(title=APP_NAME) as demo:
         with gr.Accordion("Solar details", open=False):
             sol_json = gr.JSON(label="Solar agent output")
 
+        with gr.Accordion("Forecast Receipt (verifiable history)", open=True):
+            gr.Markdown(
+                "- Download the receipt to freeze this run.\n"
+                "- If you enabled raw payloads, payload-hash verification is offline.\n"
+                "- If not enabled, you still get URLs/params/timestamps + sha256 for audit trails."
+            )
+            receipt_json = gr.JSON(label="Receipt JSON")
+            receipt_file = gr.File(label="Download receipt (.json)")
+
         btn.click(
             run_forecast,
-            inputs=[loc, seismic_mode, region, radius],
-            outputs=[header_md, table, verify_md, atm_json, sei_json, mag_json, sol_json],
+            inputs=[loc, seismic_mode, region, radius, include_raw],
+            outputs=[header_md, table, verify_md, atm_json, sei_json, mag_json, sol_json, receipt_json, receipt_file],
+        )
+
+    with gr.Tab("Verify Receipt"):
+        gr.Markdown(
+            "Upload a previously downloaded Forecast Receipt JSON to verify:\n\n"
+            "- Structural integrity\n"
+            "- Embedded payload hash checks (if raw payloads were included)\n"
+            "- Recomputed z / τ_eff / index and label against stored intermediates\n"
         )
+        up = gr.File(label="Upload receipt (.json)", file_types=[".json"])
+        vbtn = gr.Button("Verify", variant="primary")
+        vstatus = gr.Markdown()
+        vtable = gr.Dataframe(headers=["Check", "Status", "Detail"], interactive=False)
+        vbtn.click(verify_receipt, inputs=[up], outputs=[vstatus, vtable])
 
     with gr.Tab("Method (Open)"):
         gr.Markdown(INSTRUCTIONS_MD)