feat(eia): gold-standard /api/eia/petroleum (Railway seed → Redis → Vercel reads only) (#3161)

* feat(eia): move /api/eia/petroleum to gold-standard (Railway seed → Redis → Vercel reads only)

Live api.eia.gov fetches from the Vercel edge function were causing
FUNCTION_INVOCATION_TIMEOUT 504s on /api/eia/petroleum (Sydney edge →
US origin with no timeout, no cache, no stale fallback — one EIA blip
blew the 25s budget).

- New seeder scripts/seed-eia-petroleum.mjs — fetches WTI/Brent/
  production/inventory from api.eia.gov with per-fetch 15s timeouts,
  writes energy:eia-petroleum:v1 with the {_seed, data} envelope.
  Accepts 1-of-4 series; 0-of-4 routes to contract-mode RETRY so
  seed-meta stays stale and the bundle retries on next cron.
- Bundled into seed-bundle-energy-sources.mjs (daily, 90s timeout) —
  no new Railway service needed.
- Rewrote api/eia/[[...path]].js as a Redis-only reader via
  readJsonFromUpstash. Same response shape for backward compat with
  widgets/MCP/external callers. 503 + Retry-After on miss (never 504).
- Registered eiaPetroleum in api/health.js STANDALONE_KEYS + gated as
  ON_DEMAND_KEYS for the deploy window; promote to SEED_META
  (maxStaleMin: 4320) in a follow-up after ~7 days of clean cron.
- Tests: 14 seeder unit tests + 9 edge handler tests.

Audit result: /api/eia/petroleum was the only Vercel route fetching
dashboard data live. Every other fetch(https://…) in api/ is
auth/payments/notifications/user-initiated enrichment.

* fix(eia): close silent-stale window — add SEED_META + seed-health registration

Review finding on PR #3161: without a SEED_META entry, readSeedMeta
returns seedStale: null and classifyKey never reaches STALE_SEED.
That meant a broken Railway cron or missing EIA_API_KEY after the first
successful seed would keep /api/eia/petroleum serving stale data for
up to 7 days (TTL) while /api/health reported OK.

- api/health.js: add SEED_META.eiaPetroleum with maxStaleMin=4320
  (72h = 3× daily bundle cadence). Keep eiaPetroleum in ON_DEMAND_KEYS
  so the Vercel-instant / Railway-delayed deploy window doesn't CRIT
  on first seed, but stale-after-seed now properly fires STALE_SEED.
- api/seed-health.js: register energy:eia-petroleum in SEED_DOMAINS
  (intervalMin=1440) so the secondary health endpoint reports it too.
- Updated ON_DEMAND_KEYS comment to reflect freshness is now enforced.

api/eia/[[...path]].js

@@ -1,117 +1,61 @@
-// EIA (Energy Information Administration) API proxy
-// Keeps API key server-side
+// EIA (Energy Information Administration) passthrough.
+// Redis-only reader. Railway seeder `seed-eia-petroleum.mjs` (bundled in
+// `seed-bundle-energy-sources`) writes `energy:eia-petroleum:v1`; this
+// endpoint reads from Redis and never hits api.eia.gov at request time.
+// Gold standard per feedback_vercel_reads_only.md.
+
 import { getCorsHeaders, isDisallowedOrigin } from '../_cors.js';
+import { readJsonFromUpstash } from '../_upstash-json.js';
+
 export const config = { runtime: 'edge' };
 
+const CANONICAL_KEY = 'energy:eia-petroleum:v1';
+
 export default async function handler(req) {
   const cors = getCorsHeaders(req);
   if (isDisallowedOrigin(req)) {
     return new Response(JSON.stringify({ error: 'Origin not allowed' }), { status: 403, headers: cors });
   }
 
-  // Only allow GET and OPTIONS methods
   if (req.method === 'OPTIONS') {
     return new Response(null, { status: 204, headers: cors });
   }
   if (req.method !== 'GET') {
-    return Response.json({ error: 'Method not allowed' }, {
-      status: 405,
-      headers: cors,
-    });
+    return Response.json({ error: 'Method not allowed' }, { status: 405, headers: cors });
   }
 
   const url = new URL(req.url);
   const path = url.pathname.replace('/api/eia', '');
 
-  const apiKey = process.env.EIA_API_KEY;
-
-  if (!apiKey) {
-    return Response.json({
-      configured: false,
-      skipped: true,
-      reason: 'EIA_API_KEY not configured',
-    }, {
-      status: 200,
-      headers: cors,
-    });
-  }
-
-  // Health check
   if (path === '/health' || path === '') {
-    return Response.json({ configured: true }, {
-      headers: cors,
+    return Response.json({ configured: true }, { headers: cors });
+  }
+
+  if (path === '/petroleum') {
+    let data;
+    try {
+      data = await readJsonFromUpstash(CANONICAL_KEY, 3_000);
+    } catch {
+      data = null;
+    }
+
+    if (!data) {
+      return Response.json(
+        { error: 'Data not yet seeded', hint: 'Retry in a few minutes' },
+        {
+          status: 503,
+          headers: { ...cors, 'Cache-Control': 'no-store', 'Retry-After': '300' },
+        },
+      );
+    }
+
+    return Response.json(data, {
+      headers: {
+        ...cors,
+        'Cache-Control': 'public, max-age=1800, s-maxage=1800, stale-while-revalidate=86400',
+      },
     });
   }
 
-  // Petroleum data endpoint
-  if (path === '/petroleum') {
-    try {
-      const series = {
-        wti: 'PET.RWTC.W',
-        brent: 'PET.RBRTE.W',
-        production: 'PET.WCRFPUS2.W',
-        inventory: 'PET.WCESTUS1.W',
-      };
-
-      const results = {};
-
-      // Fetch all series in parallel
-      const fetchPromises = Object.entries(series).map(async ([key, seriesId]) => {
-        try {
-          const response = await fetch(
-            `https://api.eia.gov/v2/seriesid/${seriesId}?api_key=${apiKey}&num=2`,
-            { headers: { 'Accept': 'application/json' } }
-          );
-
-          if (!response.ok) return null;
-
-          const data = await response.json();
-          const values = data?.response?.data || [];
-
-          if (values.length >= 1) {
-            return {
-              key,
-              data: {
-                current: values[0]?.value,
-                previous: values[1]?.value || values[0]?.value,
-                date: values[0]?.period,
-                unit: values[0]?.unit,
-              }
-            };
-          }
-        } catch (e) {
-          console.error(`[EIA] Failed to fetch ${key}:`, e.message);
-        }
-        return null;
-      });
-
-      const fetchResults = await Promise.all(fetchPromises);
-
-      for (const result of fetchResults) {
-        if (result) {
-          results[result.key] = result.data;
-        }
-      }
-
-      return Response.json(results, {
-        headers: {
-          ...cors,
-          'Cache-Control': 'public, max-age=1800, s-maxage=1800, stale-while-revalidate=300',
-        },
-      });
-    } catch (error) {
-      console.error('[EIA] Fetch error:', error);
-      return Response.json({
-        error: 'Failed to fetch EIA data',
-      }, {
-        status: 500,
-        headers: cors,
-      });
-    }
-  }
-
-  return Response.json({ error: 'Not found' }, {
-    status: 404,
-    headers: cors,
-  });
+  return Response.json({ error: 'Not found' }, { status: 404, headers: cors });
 }