mostlyright 0.1.0-rc.7

package/dist/index.mjs

@@ -0,0 +1,953 @@
+// src/index.ts
+import { helloCore } from "@mostlyrightmd/core";
+import { helloWeather } from "@mostlyrightmd/weather";
+import { helloMarkets } from "@mostlyrightmd/markets";
+import * as core from "@mostlyrightmd/core";
+import * as markets from "@mostlyrightmd/markets";
+import * as weather from "@mostlyrightmd/weather";
+
+// src/research.ts
+import {
+  NotFoundError,
+  STATION_BY_CODE,
+  STATION_BY_ICAO,
+  settlementDateFor
+} from "@mostlyrightmd/core";
+import {
+  cacheKeyForClimate,
+  cacheKeyForObservations,
+  defaultCacheStore,
+  isLiveSource,
+  isWithinVolatileWindow,
+  isWritableMonth,
+  isWritableYear,
+  shouldSkipCacheForCurrentLstMonth,
+  shouldSkipCacheForCurrentLstYear
+} from "@mostlyrightmd/core/internal/cache";
+import { mergeClimate, mergeObservations } from "@mostlyrightmd/core/internal/merge";
+import {
+  buildPairs
+} from "@mostlyrightmd/core/internal/pairs";
+import {
+  awcToObservation,
+  downloadCliRange,
+  downloadGhcnh,
+  downloadIemAsos,
+  fetchAwcMetars,
+  parseCliResponse,
+  parseGhcnhPsv,
+  parseIemCsv
+} from "@mostlyrightmd/weather";
+var AWC_MAX_HOURS = 168;
+async function resolveCache(opts) {
+  if (opts.cache === null) return null;
+  if (opts.cache !== void 0) return opts.cache;
+  return await defaultCacheStore();
+}
+var DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+function normalizeStation(input) {
+  const raw = input.trim().toUpperCase();
+  if (raw.length === 0) {
+    throw new Error("station must be a non-empty string");
+  }
+  const byIcao = STATION_BY_ICAO.get(raw);
+  if (byIcao !== void 0) {
+    if (byIcao.code === null) {
+      throw new Error(`station ${JSON.stringify(raw)} has no 3-letter NWS code`);
+    }
+    return {
+      code: byIcao.code,
+      icao: byIcao.icao,
+      tz: byIcao.tz,
+      country: byIcao.country,
+      ghcnhId: byIcao.ghcnh_id
+    };
+  }
+  const byCode = STATION_BY_CODE.get(raw);
+  if (byCode !== void 0) {
+    if (byCode.code === null) {
+      throw new Error(`station ${JSON.stringify(raw)} has no 3-letter NWS code`);
+    }
+    return {
+      code: byCode.code,
+      icao: byCode.icao,
+      tz: byCode.tz,
+      country: byCode.country,
+      ghcnhId: byCode.ghcnh_id
+    };
+  }
+  if (raw.startsWith("K") && raw.length === 4) {
+    const stripped = raw.slice(1);
+    const retry = STATION_BY_CODE.get(stripped);
+    if (retry !== void 0 && retry.code !== null) {
+      return {
+        code: retry.code,
+        icao: retry.icao,
+        tz: retry.tz,
+        country: retry.country,
+        ghcnhId: retry.ghcnh_id
+      };
+    }
+  }
+  throw new Error(
+    `unknown station ${JSON.stringify(input)} \u2014 not found in STATION_BY_CODE or STATION_BY_ICAO`
+  );
+}
+function parseIsoDate(s) {
+  if (!DATE_RE.test(s)) {
+    throw new Error(`expected YYYY-MM-DD, got ${JSON.stringify(s)}`);
+  }
+  const [yStr, mStr, dStr] = s.split("-");
+  const year = Number(yStr);
+  const month = Number(mStr);
+  const day = Number(dStr);
+  const ms = Date.UTC(year, month - 1, day);
+  const d = new Date(ms);
+  if (d.getUTCFullYear() !== year || d.getUTCMonth() !== month - 1 || d.getUTCDate() !== day) {
+    throw new Error(`invalid calendar date ${JSON.stringify(s)}`);
+  }
+  return d;
+}
+function formatDate(d) {
+  const y = d.getUTCFullYear();
+  const m = d.getUTCMonth() + 1;
+  const day = d.getUTCDate();
+  const mm = m < 10 ? `0${m}` : `${m}`;
+  const dd = day < 10 ? `0${day}` : `${day}`;
+  return `${y}-${mm}-${dd}`;
+}
+function buildDateList(fromDate, toDate) {
+  const from = parseIsoDate(fromDate);
+  const to = parseIsoDate(toDate);
+  if (from.getTime() > to.getTime()) {
+    throw new Error(`fromDate (${fromDate}) must be <= toDate (${toDate})`);
+  }
+  const dates = [];
+  for (let cursor = from.getTime(); cursor <= to.getTime(); cursor += 24 * 36e5) {
+    dates.push(formatDate(new Date(cursor)));
+  }
+  return dates;
+}
+function plusOneDay(isoDate) {
+  const d = parseIsoDate(isoDate);
+  return formatDate(new Date(d.getTime() + 24 * 36e5));
+}
+function isUsStation(station) {
+  return station.country === "US";
+}
+function anyDateOverlapsAwc(toDate, hours, now) {
+  const to = parseIsoDate(toDate);
+  const toEndMs = to.getTime() + 24 * 36e5;
+  const nowMs = now.getTime();
+  const cutoffMs = nowMs - hours * 36e5;
+  return toEndMs >= cutoffMs;
+}
+function observedSettlementDate(observedAt, station) {
+  const ms = Date.parse(observedAt);
+  if (!Number.isFinite(ms)) return null;
+  try {
+    return settlementDateFor(new Date(ms), station);
+  } catch {
+    return null;
+  }
+}
+function sortByObservedAtThenSource(rows) {
+  return [...rows].sort((a, b) => {
+    if (a.observed_at < b.observed_at) return -1;
+    if (a.observed_at > b.observed_at) return 1;
+    if (a.source < b.source) return -1;
+    if (a.source > b.source) return 1;
+    return 0;
+  });
+}
+function isYearVolatile(year, now) {
+  const yearEnd = `${String(year).padStart(4, "0")}-12-31`;
+  return isWithinVolatileWindow(yearEnd, formatDate(now), 30);
+}
+function lastDayOfMonth(year, month) {
+  const d = new Date(Date.UTC(year, month, 0));
+  return formatDate(d);
+}
+function isMonthVolatile(year, month, now) {
+  return isWithinVolatileWindow(lastDayOfMonth(year, month), formatDate(now), 30);
+}
+function monthsInRange(fromIsoDate, toIsoDate) {
+  const from = parseIsoDate(fromIsoDate);
+  const to = parseIsoDate(toIsoDate);
+  if (from.getTime() > to.getTime()) {
+    throw new Error(`fromDate (${fromIsoDate}) must be <= toDate (${toIsoDate})`);
+  }
+  const pairs = [];
+  let y = from.getUTCFullYear();
+  let m = from.getUTCMonth() + 1;
+  const endY = to.getUTCFullYear();
+  const endM = to.getUTCMonth() + 1;
+  while (y < endY || y === endY && m <= endM) {
+    pairs.push([y, m]);
+    m += 1;
+    if (m > 12) {
+      m = 1;
+      y += 1;
+    }
+  }
+  return pairs;
+}
+async function fetchCliWithCache(fetchIcao, cacheCode, fromYear, toYear, opts, cache, now) {
+  const acc = [];
+  for (let year = fromYear; year <= toYear; year++) {
+    const writable = isWritableYear(year, now);
+    const skipCurrentYear = shouldSkipCacheForCurrentLstYear(cacheCode, year, now);
+    const skipVolatile = isYearVolatile(year, now);
+    const skip = !writable || skipCurrentYear || skipVolatile;
+    if (cache !== null && !skip) {
+      let cached = null;
+      try {
+        cached = await cache.get(cacheKeyForClimate(cacheCode, year));
+      } catch (cacheErr) {
+        console.warn(
+          `[mostlyright] CLI cache.get failed for code=${cacheCode} year=${year}; falling back to live fetch:`,
+          cacheErr
+        );
+      }
+      if (cached !== null) {
+        acc.push(...cached);
+        continue;
+      }
+    }
+    const cliOpts = {};
+    if (opts.signal !== void 0) cliOpts.signal = opts.signal;
+    if (opts.cliPolitenessMs !== void 0) cliOpts.politenessMs = opts.cliPolitenessMs;
+    const cliRaw = await downloadCliRange(fetchIcao, year, year, cliOpts);
+    const parsed = parseCliResponse(cliRaw, cacheCode);
+    acc.push(...parsed);
+    const sample = parsed[0]?.source;
+    if (cache !== null && !skip && !isLiveSource(sample)) {
+      try {
+        await cache.set(cacheKeyForClimate(cacheCode, year), parsed);
+      } catch (cacheErr) {
+        console.warn(
+          `[mostlyright] CLI cache.set failed for code=${cacheCode} year=${year}; in-memory rows preserved:`,
+          cacheErr
+        );
+      }
+    }
+  }
+  return acc;
+}
+async function fetchIemAsosWithCache(stationCode, _fromYear, _extendedToYear, fromDate, extendedTo, opts, cache, now) {
+  const acc = [];
+  const yearByReportType = /* @__PURE__ */ new Map();
+  async function fetchYearOnce(year, reportType) {
+    const memoKey = `${year}:${reportType}`;
+    const cached = yearByReportType.get(memoKey);
+    if (cached !== void 0) return cached;
+    const iemOpts = {
+      reportType,
+      politenessMs: opts.iemPolitenessMs ?? 1e3
+    };
+    if (opts.signal !== void 0) iemOpts.signal = opts.signal;
+    const chunks = await downloadIemAsos(stationCode, `${year}-01-01`, `${year}-12-31`, iemOpts);
+    const fetched = [];
+    for (const chunk of chunks) {
+      const parsed = parseIemCsv(chunk.csv, {
+        observationTypeOverride: reportType === 3 ? "METAR" : "SPECI"
+      });
+      fetched.push(...parsed);
+    }
+    yearByReportType.set(memoKey, fetched);
+    return fetched;
+  }
+  function filterMonth(rows, year, month) {
+    const yyyy = String(year).padStart(4, "0");
+    const mm = String(month).padStart(2, "0");
+    const prefix = `${yyyy}-${mm}-`;
+    const out = [];
+    for (const r of rows) {
+      if (r.observed_at.startsWith(prefix)) out.push(r);
+    }
+    return out;
+  }
+  const pairs = monthsInRange(fromDate, extendedTo);
+  for (const [year, month] of pairs) {
+    const cacheKey = cacheKeyForObservations(stationCode, year, month, "iem");
+    const writable = isWritableMonth(year, month, now);
+    const skipCurrentMonth = shouldSkipCacheForCurrentLstMonth(stationCode, year, month, now);
+    const skipVolatile = isMonthVolatile(year, month, now);
+    const skipCache = !writable || skipCurrentMonth || skipVolatile;
+    let monthRows = null;
+    if (cache !== null && !skipCache) {
+      try {
+        const cached = await cache.get(cacheKey);
+        if (cached !== null) monthRows = cached;
+      } catch (cacheErr) {
+        console.warn(
+          `[mostlyright] IEM ASOS cache.get failed for key=${cacheKey}; falling back to live fetch:`,
+          cacheErr
+        );
+      }
+    }
+    if (monthRows === null) {
+      const metar = await fetchYearOnce(year, 3);
+      const speci = await fetchYearOnce(year, 4);
+      const monthMetar = filterMonth(metar, year, month);
+      const monthSpeci = filterMonth(speci, year, month);
+      monthRows = [...monthMetar, ...monthSpeci];
+      const sample = monthRows[0]?.source;
+      if (cache !== null && !skipCache && !isLiveSource(sample)) {
+        try {
+          await cache.set(cacheKey, monthRows);
+        } catch (cacheErr) {
+          console.warn(
+            `[mostlyright] IEM ASOS cache.set failed for key=${cacheKey}; in-memory rows preserved:`,
+            cacheErr
+          );
+        }
+      }
+    }
+    for (const obs of monthRows) {
+      const obsDate = obs.observed_at.slice(0, 10);
+      if (obsDate >= fromDate && obsDate <= extendedTo) acc.push(obs);
+    }
+  }
+  return acc;
+}
+async function fetchGhcnhWithCache(stationCode, ghcnhId, fromDate, extendedTo, opts, cache, now) {
+  const acc = [];
+  const yearCache = /* @__PURE__ */ new Map();
+  async function fetchYearOnce(year) {
+    const cached = yearCache.get(year);
+    if (cached !== void 0) return cached;
+    const ghcnhOpts = {};
+    if (opts.signal !== void 0) ghcnhOpts.signal = opts.signal;
+    let parsed;
+    try {
+      const yr = await downloadGhcnh(ghcnhId, year, ghcnhOpts);
+      parsed = parseGhcnhPsv(yr.psv);
+    } catch (err) {
+      if (err instanceof NotFoundError) {
+        parsed = [];
+      } else {
+        throw err;
+      }
+    }
+    yearCache.set(year, parsed);
+    return parsed;
+  }
+  function filterMonth(rows, year, month) {
+    const yyyy = String(year).padStart(4, "0");
+    const mm = String(month).padStart(2, "0");
+    const prefix = `${yyyy}-${mm}-`;
+    const out = [];
+    for (const r of rows) {
+      if (r.observed_at.startsWith(prefix) && r.station_code === stationCode) out.push(r);
+    }
+    return out;
+  }
+  const pairs = monthsInRange(fromDate, extendedTo);
+  for (const [year, month] of pairs) {
+    const cacheKey = cacheKeyForObservations(stationCode, year, month, "ghcnh");
+    const writable = isWritableMonth(year, month, now);
+    const skipCurrentMonth = shouldSkipCacheForCurrentLstMonth(stationCode, year, month, now);
+    const skipVolatile = isMonthVolatile(year, month, now);
+    const skipCache = !writable || skipCurrentMonth || skipVolatile;
+    let monthRows = null;
+    if (cache !== null && !skipCache) {
+      try {
+        const cached = await cache.get(cacheKey);
+        if (cached !== null) monthRows = cached;
+      } catch (cacheErr) {
+        console.warn(
+          `[mostlyright] GHCNh cache.get failed for key=${cacheKey}; falling back to live fetch:`,
+          cacheErr
+        );
+      }
+    }
+    if (monthRows === null) {
+      const yearRows = await fetchYearOnce(year);
+      monthRows = filterMonth(yearRows, year, month);
+      const sample = monthRows[0]?.source;
+      if (cache !== null && !skipCache && !isLiveSource(sample)) {
+        try {
+          await cache.set(cacheKey, monthRows);
+        } catch (cacheErr) {
+          console.warn(
+            `[mostlyright] GHCNh cache.set failed for key=${cacheKey}; in-memory rows preserved:`,
+            cacheErr
+          );
+        }
+      }
+    }
+    for (const obs of monthRows) {
+      const obsDate = obs.observed_at.slice(0, 10);
+      if (obsDate >= fromDate && obsDate <= extendedTo) acc.push(obs);
+    }
+  }
+  return acc;
+}
+async function research(station, fromDate, toDate, opts = {}) {
+  const hasCity = typeof opts.city === "string" && opts.city.length > 0;
+  const hasContract = typeof opts.contract === "string" && opts.contract.length > 0;
+  const hasContracts = Array.isArray(opts.contracts) && opts.contracts.length > 0;
+  const hasStation = typeof station === "string" && station.length > 0;
+  const selectorCount = Number(hasStation) + Number(hasCity) + Number(hasContract) + Number(hasContracts);
+  if (selectorCount === 0) {
+    throw new Error(
+      "research(): exactly one of station, opts.city, opts.contract, opts.contracts must be provided"
+    );
+  }
+  if (selectorCount > 1) {
+    const names = [];
+    if (hasStation) names.push("station");
+    if (hasCity) names.push("city");
+    if (hasContract) names.push("contract");
+    if (hasContracts) names.push("contracts");
+    throw new Error(`research(): selectors are mutually exclusive; got ${JSON.stringify(names)}`);
+  }
+  if (opts.sources !== void 0 && opts.source !== void 0) {
+    throw new Error("research(): sources and source are mutually exclusive");
+  }
+  if (opts.sources !== void 0 || opts.source !== void 0) {
+    throw new Error(
+      "research(): sources / source validation surface is shipped in Phase 10 v0.2 but the data-selection wiring lands in v0.3. For Mode 2 single-source pinning today, use `researchBySource(station, source, ...)` from @mostlyrightmd/meta."
+    );
+  }
+  if (opts.stationOverride !== void 0 && !hasContract) {
+    throw new Error(
+      "research(): stationOverride requires contract (not standalone station/city/contracts)"
+    );
+  }
+  if (opts.includeTrades === true && !(hasContract || hasContracts)) {
+    throw new Error(
+      "research(): includeTrades requires contract or contracts (station/city selectors have no trade timeseries)"
+    );
+  }
+  if (hasCity || hasContract || hasContracts) {
+    throw new Error(
+      "research(): city/contract/contracts selectors are validated in Phase 10 v0.2 but the multi-station/multi-issuer JOIN + trade attachment lands in v0.3. For now, use `discover({city})` to find the station then call `research(station, fromDate, toDate)` directly."
+    );
+  }
+  const resolved = normalizeStation(station);
+  const dates = buildDateList(fromDate, toDate);
+  const extendedTo = plusOneDay(toDate);
+  const fromYear = Number(fromDate.slice(0, 4));
+  const toYear = Number(toDate.slice(0, 4));
+  const extendedToYear = Number(extendedTo.slice(0, 4));
+  const baseOpts = {};
+  if (opts.signal !== void 0) baseOpts.signal = opts.signal;
+  const cache = await resolveCache(opts);
+  const cacheNow = opts.now ?? /* @__PURE__ */ new Date();
+  let mergedClimate = [];
+  try {
+    const cliRows = await fetchCliWithCache(
+      resolved.icao,
+      resolved.code,
+      fromYear,
+      toYear,
+      opts,
+      cache,
+      cacheNow
+    );
+    mergedClimate = mergeClimate(cliRows);
+  } catch (err) {
+    if (err instanceof DOMException && (err.name === "AbortError" || err.name === "TimeoutError")) {
+      throw err;
+    }
+  }
+  const awcHours = opts.awcHours ?? AWC_MAX_HOURS;
+  const awcRows = [];
+  if (anyDateOverlapsAwc(toDate, awcHours, opts.now ?? /* @__PURE__ */ new Date())) {
+    const awcOpts = { hours: awcHours };
+    if (opts.signal !== void 0) awcOpts.signal = opts.signal;
+    const awcRaw = await fetchAwcMetars([resolved.icao], awcOpts);
+    for (const m of awcRaw) {
+      const obs = awcToObservation(m);
+      if (obs !== null) awcRows.push(obs);
+    }
+  }
+  const iemRows = await fetchIemAsosWithCache(
+    resolved.code,
+    fromYear,
+    extendedToYear,
+    fromDate,
+    extendedTo,
+    opts,
+    cache,
+    cacheNow
+  );
+  let ghcnhRows = [];
+  if (isUsStation(resolved) && resolved.ghcnhId !== null && resolved.ghcnhId.length > 0) {
+    ghcnhRows = await fetchGhcnhWithCache(
+      resolved.code,
+      resolved.ghcnhId,
+      fromDate,
+      extendedTo,
+      opts,
+      cache,
+      cacheNow
+    );
+  }
+  const combinedRaw = [...awcRows, ...iemRows, ...ghcnhRows];
+  const sorted = sortByObservedAtThenSource(combinedRaw);
+  const merged = mergeObservations(sorted);
+  const observationsByDate = {};
+  const dateLo = dates[0] ?? "";
+  const dateHi = dates[dates.length - 1] ?? "";
+  for (const obs of merged) {
+    const settleDate = observedSettlementDate(obs.observed_at, resolved.code);
+    if (settleDate === null) continue;
+    if (settleDate < dateLo || settleDate > dateHi) continue;
+    let bucket = observationsByDate[settleDate];
+    if (bucket === void 0) {
+      bucket = [];
+      observationsByDate[settleDate] = bucket;
+    }
+    bucket.push(obs);
+  }
+  const climateByDate = {};
+  for (const cli of mergedClimate) {
+    climateByDate[cli.observation_date] = cli;
+  }
+  return buildPairs(resolved.code, dates, observationsByDate, climateByDate);
+}
+
+// src/mode2.ts
+import {
+  NotFoundError as NotFoundError2,
+  STATION_BY_CODE as STATION_BY_CODE2,
+  STATION_BY_ICAO as STATION_BY_ICAO2,
+  SourceMismatchError
+} from "@mostlyrightmd/core";
+import {
+  awcToObservation as awcToObservation2,
+  downloadGhcnh as downloadGhcnh2,
+  downloadIemAsos as downloadIemAsos2,
+  fetchAwcMetars as fetchAwcMetars2,
+  parseGhcnhPsv as parseGhcnhPsv2,
+  parseIemCsv as parseIemCsv2
+} from "@mostlyrightmd/weather";
+var MODE2_SOURCES = ["iem.archive", "iem.live", "awc.live", "ghcnh.archive"];
+var SOURCE_ALIASES = /* @__PURE__ */ new Map([
+  ["iem.archive", /* @__PURE__ */ new Set(["iem", "iem.archive"])],
+  ["iem.live", /* @__PURE__ */ new Set(["iem", "iem.live"])],
+  ["awc.live", /* @__PURE__ */ new Set(["awc", "awc.live"])],
+  ["ghcnh.archive", /* @__PURE__ */ new Set(["ghcnh", "ghcnh.archive"])]
+]);
+function isMode2Source(value) {
+  return typeof value === "string" && MODE2_SOURCES.includes(value);
+}
+function assertSourceIdentity(rows, expected, role = "observations") {
+  const accept = typeof expected === "string" ? /* @__PURE__ */ new Set([expected]) : expected;
+  const expectedLabel = typeof expected === "string" ? expected : [...accept].sort().join("|");
+  const distinct = /* @__PURE__ */ new Set();
+  let bad = 0;
+  for (const r of rows) {
+    const src = r?.source;
+    if (typeof src !== "string") continue;
+    if (!accept.has(src)) {
+      distinct.add(src);
+      bad += 1;
+    }
+  }
+  if (bad === 0) return;
+  const others = [...distinct].sort();
+  const first = others[0] ?? "<unknown>";
+  throw new SourceMismatchError(
+    `Mode 2 dispatch requested '${expectedLabel}' but received ${bad} row(s) with other sources: [${others.map((s) => `'${s}'`).join(", ")}]`,
+    {
+      schemaSource: expectedLabel,
+      dataSource: first,
+      role,
+      catalogWarning: null
+    }
+  );
+}
+var AWC_MAX_HOURS2 = 168;
+var DATE_RE2 = /^\d{4}-\d{2}-\d{2}$/;
+function resolveStation(input) {
+  const raw = input.trim().toUpperCase();
+  if (raw.length === 0) {
+    throw new Error("station must be a non-empty string");
+  }
+  const byIcao = STATION_BY_ICAO2.get(raw);
+  if (byIcao !== void 0) {
+    if (byIcao.code === null) {
+      throw new Error(`station ${JSON.stringify(raw)} has no 3-letter NWS code`);
+    }
+    return {
+      code: byIcao.code,
+      icao: byIcao.icao,
+      country: byIcao.country,
+      ghcnhId: byIcao.ghcnh_id
+    };
+  }
+  const byCode = STATION_BY_CODE2.get(raw);
+  if (byCode !== void 0) {
+    if (byCode.code === null) {
+      throw new Error(`station ${JSON.stringify(raw)} has no 3-letter NWS code`);
+    }
+    return {
+      code: byCode.code,
+      icao: byCode.icao,
+      country: byCode.country,
+      ghcnhId: byCode.ghcnh_id
+    };
+  }
+  if (raw.startsWith("K") && raw.length === 4) {
+    const stripped = raw.slice(1);
+    const retry = STATION_BY_CODE2.get(stripped);
+    if (retry !== void 0 && retry.code !== null) {
+      return {
+        code: retry.code,
+        icao: retry.icao,
+        country: retry.country,
+        ghcnhId: retry.ghcnh_id
+      };
+    }
+  }
+  throw new Error(
+    `unknown station ${JSON.stringify(input)} \u2014 not found in STATION_BY_CODE or STATION_BY_ICAO`
+  );
+}
+function validateDateFormat(label, value) {
+  if (!DATE_RE2.test(value)) {
+    throw new Error(`${label} must be YYYY-MM-DD, got ${JSON.stringify(value)}`);
+  }
+}
+function yearOf(isoDate) {
+  return Number(isoDate.slice(0, 4));
+}
+async function researchBySource(station, source, fromDate, toDate, opts = {}) {
+  if (!isMode2Source(source)) {
+    throw new Error(
+      `Mode 2 source must be one of ${JSON.stringify(
+        MODE2_SOURCES
+      )}; got ${JSON.stringify(source)}`
+    );
+  }
+  if (source === "iem.live") {
+    throw new Error(
+      "Mode 2 source 'iem.live' not yet implemented in v0.1.0 (Parity-Ticket: requires per-month live IEM endpoint not yet ported). Use 'iem.archive' for historical IEM rows."
+    );
+  }
+  validateDateFormat("fromDate", fromDate);
+  validateDateFormat("toDate", toDate);
+  if (fromDate > toDate) {
+    throw new Error(`fromDate (${fromDate}) must be <= toDate (${toDate})`);
+  }
+  const resolved = resolveStation(station);
+  const accept = SOURCE_ALIASES.get(source);
+  if (accept === void 0) {
+    throw new Error(`internal: no SOURCE_ALIASES entry for '${source}'`);
+  }
+  let rows;
+  switch (source) {
+    case "awc.live": {
+      const awcOpts = {
+        hours: opts.awcHours ?? AWC_MAX_HOURS2
+      };
+      if (opts.signal !== void 0) awcOpts.signal = opts.signal;
+      const raw = await fetchAwcMetars2([resolved.icao], awcOpts);
+      const parsed = [];
+      for (const m of raw) {
+        const obs = awcToObservation2(m);
+        if (obs !== null) parsed.push(obs);
+      }
+      rows = parsed.filter((r) => {
+        const d = r.observed_at.slice(0, 10);
+        return d >= fromDate && d <= toDate;
+      });
+      break;
+    }
+    case "iem.archive": {
+      const fromYear = yearOf(fromDate);
+      const toYear = yearOf(toDate);
+      const collected = [];
+      for (let year = fromYear; year <= toYear; year++) {
+        for (const reportType of [3, 4]) {
+          const iemOpts = {
+            reportType,
+            politenessMs: opts.iemPolitenessMs ?? 1e3
+          };
+          if (opts.signal !== void 0) iemOpts.signal = opts.signal;
+          const chunks = await downloadIemAsos2(
+            resolved.code,
+            `${year}-01-01`,
+            `${year}-12-31`,
+            iemOpts
+          );
+          for (const chunk of chunks) {
+            const parsed = parseIemCsv2(chunk.csv, {
+              observationTypeOverride: reportType === 3 ? "METAR" : "SPECI"
+            });
+            collected.push(...parsed);
+          }
+        }
+      }
+      rows = collected.filter((r) => {
+        const d = r.observed_at.slice(0, 10);
+        return d >= fromDate && d <= toDate;
+      });
+      break;
+    }
+    case "ghcnh.archive": {
+      if (resolved.country !== "US" || resolved.ghcnhId === null || resolved.ghcnhId.length === 0) {
+        throw new NotFoundError2(
+          `GHCNh archive is US-only; station ${JSON.stringify(station)} (country=${resolved.country ?? "null"}, ghcnh_id=${resolved.ghcnhId === null ? "null" : JSON.stringify(resolved.ghcnhId)}) has no GHCNh coverage`
+        );
+      }
+      const fromYear = yearOf(fromDate);
+      const toYear = yearOf(toDate);
+      const collected = [];
+      for (let year = fromYear; year <= toYear; year++) {
+        const ghcnhOpts = {};
+        if (opts.signal !== void 0) ghcnhOpts.signal = opts.signal;
+        try {
+          const yr = await downloadGhcnh2(resolved.ghcnhId, year, ghcnhOpts);
+          const parsed = parseGhcnhPsv2(yr.psv);
+          for (const r of parsed) {
+            if (r.station_code === resolved.code) collected.push(r);
+          }
+        } catch (err) {
+          if (err instanceof NotFoundError2) continue;
+          throw err;
+        }
+      }
+      rows = collected.filter((r) => {
+        const d = r.observed_at.slice(0, 10);
+        return d >= fromDate && d <= toDate;
+      });
+      break;
+    }
+  }
+  const filtered = rows.filter((r) => accept.has(r.source));
+  assertSourceIdentity(filtered, accept, "observations");
+  return filtered;
+}
+
+// src/compose.ts
+import {
+  KALSHI_SETTLEMENT_STATIONS,
+  POLYMARKET_CITY_STATIONS
+} from "@mostlyrightmd/markets";
+import { POLYMARKET_KNOWN_WRONG_STATIONS } from "@mostlyrightmd/markets/polymarket";
+var SELECTOR_NAMES = ["station", "city", "contract", "contracts"];
+var KALSHI_TICKER_ALIASES = {
+  NY: "NYC"
+};
+var CITY_SLUG_ALIASES = {
+  // short_kalshi (lower) → [polymarket_long, kalshi_upper]
+  nyc: ["nyc", "NYC"],
+  chi: ["chicago", "CHI"],
+  lax: ["los_angeles", "LAX"],
+  mia: ["miami", "MIA"],
+  den: ["denver", "DEN"],
+  bos: ["boston", "BOS"],
+  aus: ["austin", "AUS"],
+  dca: ["washington_dc", "DCA"],
+  phl: ["philadelphia", "PHL"],
+  sfo: ["san_francisco", "SFO"],
+  sea: ["seattle", "SEA"],
+  atl: ["atlanta", "ATL"],
+  hou: ["houston", "HOU"],
+  dal: ["dallas", "DAL"],
+  phx: ["phoenix", "PHX"],
+  msp: ["minneapolis", "MSP"],
+  dtw: ["detroit", "DTW"]
+};
+var CITY_SLUG_ALIASES_REVERSE = (() => {
+  const out = {};
+  for (const [shortLower, [longPoly, kalshiUpper]] of Object.entries(CITY_SLUG_ALIASES)) {
+    out[longPoly] = [shortLower, kalshiUpper];
+  }
+  return out;
+})();
+function normalizeCitySlugs(city) {
+  const lower = city.toLowerCase();
+  const upper = city.toUpperCase();
+  const direct = CITY_SLUG_ALIASES[lower];
+  if (direct !== void 0) return direct;
+  const reverse = CITY_SLUG_ALIASES_REVERSE[lower];
+  if (reverse !== void 0) return [lower, reverse[1]];
+  return [lower, upper];
+}
+function validateSelectors(args) {
+  const provided = [];
+  if (typeof args.station === "string" && args.station.length > 0) provided.push("station");
+  if (typeof args.city === "string" && args.city.length > 0) provided.push("city");
+  if (typeof args.contract === "string" && args.contract.length > 0) provided.push("contract");
+  if (Array.isArray(args.contracts) && args.contracts.length > 0) provided.push("contracts");
+  if (provided.length === 0) {
+    throw new Error(
+      "research(): exactly one of station, city, contract, contracts must be provided"
+    );
+  }
+  if (provided.length > 1) {
+    throw new Error(
+      `research(): selectors are mutually exclusive; got ${JSON.stringify(provided)}`
+    );
+  }
+  return provided[0];
+}
+function resolveContract(contractId) {
+  if (typeof contractId !== "string" || !contractId.includes(":")) {
+    throw new TypeError(`contract id must be \`<issuer>:<id>\`; got ${JSON.stringify(contractId)}`);
+  }
+  const colonIdx = contractId.indexOf(":");
+  const issuer = contractId.slice(0, colonIdx).toLowerCase();
+  const raw = contractId.slice(colonIdx + 1);
+  const rawUpper = raw.toUpperCase();
+  if (issuer === "kalshi") {
+    let normalized = rawUpper;
+    if (normalized.startsWith("KX")) {
+      normalized = `K${normalized.slice(2)}`;
+    }
+    const cityOnly = normalized.split("-", 1)[0] ?? "";
+    let cityTickerRaw = null;
+    if (cityOnly.startsWith("KHIGH") && cityOnly.length > 5) {
+      cityTickerRaw = cityOnly.slice(5);
+    } else if (cityOnly.startsWith("KLOW") && cityOnly.length > 4) {
+      cityTickerRaw = cityOnly.slice(4);
+    } else {
+      throw new Error(
+        `unsupported kalshi contract format: ${JSON.stringify(raw)}; expected KHIGH<CITY>* / KXHIGH<CITY>* / KLOW<CITY>* / KXLOW<CITY>* prefix`
+      );
+    }
+    const cityTicker = KALSHI_TICKER_ALIASES[cityTickerRaw] ?? cityTickerRaw;
+    const entry = KALSHI_SETTLEMENT_STATIONS[cityTicker];
+    if (entry === void 0) {
+      throw new Error(`unknown Kalshi city ticker: ${JSON.stringify(cityTicker)}`);
+    }
+    return [entry.station, "kalshi"];
+  }
+  if (issuer === "polymarket") {
+    throw new Error(
+      "polymarket contract resolution requires event_id \u2192 station lookup via polymarketDiscover()/polymarketSettle(); Phase 10 v0.2 defers this to v0.3. Use `city: 'nyc'` or pass `stationOverride` until then."
+    );
+  }
+  throw new Error(
+    `unknown issuer prefix: ${JSON.stringify(issuer)}; expected kalshi or polymarket`
+  );
+}
+function resolveCity(city) {
+  if (typeof city !== "string" || !city) {
+    throw new Error(`city must be a non-empty string; got ${JSON.stringify(city)}`);
+  }
+  const [polySlug, kalshiSlug] = normalizeCitySlugs(city);
+  const out = [];
+  const kalshi = KALSHI_SETTLEMENT_STATIONS[kalshiSlug];
+  if (kalshi !== void 0 && !out.includes(kalshi.station)) {
+    out.push(kalshi.station);
+  }
+  const poly = POLYMARKET_CITY_STATIONS[polySlug];
+  if (poly !== void 0) {
+    for (const measure of ["default", "high", "low"]) {
+      const st = poly[measure];
+      if (typeof st === "string" && !out.includes(st)) out.push(st);
+    }
+  }
+  const wrong = POLYMARKET_KNOWN_WRONG_STATIONS[polySlug];
+  if (wrong !== void 0) {
+    const sortedWrong = [...wrong].sort();
+    for (const st of sortedWrong) {
+      if (!out.includes(st)) out.push(st);
+    }
+  }
+  if (out.length === 0) {
+    throw new Error(`unknown city ${JSON.stringify(city)}; not in kalshi or polymarket catalogs`);
+  }
+  return out;
+}
+function annotateSettlesFor(station, city) {
+  if (city === null) return [];
+  const [polySlug, kalshiSlug] = normalizeCitySlugs(city);
+  const out = [];
+  const kalshi = KALSHI_SETTLEMENT_STATIONS[kalshiSlug];
+  if (kalshi !== void 0 && kalshi.station === station) {
+    out.push(`kalshi:${kalshiSlug}`);
+  }
+  const poly = POLYMARKET_CITY_STATIONS[polySlug];
+  if (poly !== void 0) {
+    for (const measure of ["default", "high", "low"]) {
+      if (poly[measure] === station) {
+        out.push(`polymarket:${polySlug}`);
+        break;
+      }
+    }
+  }
+  return out.sort();
+}
+function buildOverrideWarning(contractStation, overrideStation) {
+  return {
+    kind: "StationOverrideWarning",
+    contractStation,
+    overrideStation,
+    message: `stationOverride=${JSON.stringify(overrideStation)} differs from contract's canonical settlement station ${JSON.stringify(contractStation)}; output row will carry settlementMismatch=true`
+  };
+}
+
+// src/discover.ts
+function discover(args) {
+  if (typeof args !== "object" || args === null) {
+    throw new TypeError(`discover(): args must be an object; got ${typeof args}`);
+  }
+  const stations = resolveCity(args.city);
+  const rows = stations.map((station) => ({
+    city: args.city,
+    station,
+    settlesFor: annotateSettlesFor(station, args.city)
+  }));
+  return Object.freeze({
+    rows: Object.freeze(rows),
+    city: args.city,
+    source: "discover"
+  });
+}
+
+// src/index.ts
+import {
+  POLITE_FLOORS_S,
+  SOURCE_IDENTITY_TAGS,
+  SUPPORTED_SOURCES,
+  isLiveSource as isLiveSource2,
+  latest,
+  sourceTag,
+  stream,
+  validatePollSeconds,
+  validateSource
+} from "@mostlyrightmd/weather";
+import { LiveStreamError, NoLiveDataError } from "@mostlyrightmd/core";
+var version = "0.0.0";
+export {
+  LiveStreamError,
+  MODE2_SOURCES,
+  NoLiveDataError,
+  POLITE_FLOORS_S,
+  SELECTOR_NAMES,
+  SOURCE_ALIASES,
+  SOURCE_IDENTITY_TAGS,
+  SUPPORTED_SOURCES,
+  annotateSettlesFor,
+  assertSourceIdentity,
+  buildOverrideWarning,
+  core,
+  discover,
+  helloCore,
+  helloMarkets,
+  helloWeather,
+  isLiveSource2 as isLiveSource,
+  isMode2Source,
+  latest,
+  markets,
+  research,
+  researchBySource,
+  resolveCity,
+  resolveContract,
+  sourceTag,
+  stream,
+  validatePollSeconds,
+  validateSelectors,
+  validateSource,
+  version,
+  weather
+};
+//# sourceMappingURL=index.mjs.map