mostlyright 0.1.0-rc.7

package/dist/index.cjs

@@ -0,0 +1,967 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  LiveStreamError: () => import_core4.LiveStreamError,
+  MODE2_SOURCES: () => MODE2_SOURCES,
+  NoLiveDataError: () => import_core4.NoLiveDataError,
+  POLITE_FLOORS_S: () => import_weather4.POLITE_FLOORS_S,
+  SELECTOR_NAMES: () => SELECTOR_NAMES,
+  SOURCE_ALIASES: () => SOURCE_ALIASES,
+  SOURCE_IDENTITY_TAGS: () => import_weather4.SOURCE_IDENTITY_TAGS,
+  SUPPORTED_SOURCES: () => import_weather4.SUPPORTED_SOURCES,
+  annotateSettlesFor: () => annotateSettlesFor,
+  assertSourceIdentity: () => assertSourceIdentity,
+  buildOverrideWarning: () => buildOverrideWarning,
+  core: () => core,
+  discover: () => discover,
+  helloCore: () => import_core3.helloCore,
+  helloMarkets: () => import_markets2.helloMarkets,
+  helloWeather: () => import_weather3.helloWeather,
+  isLiveSource: () => import_weather4.isLiveSource,
+  isMode2Source: () => isMode2Source,
+  latest: () => import_weather4.latest,
+  markets: () => markets,
+  research: () => research,
+  researchBySource: () => researchBySource,
+  resolveCity: () => resolveCity,
+  resolveContract: () => resolveContract,
+  sourceTag: () => import_weather4.sourceTag,
+  stream: () => import_weather4.stream,
+  validatePollSeconds: () => import_weather4.validatePollSeconds,
+  validateSelectors: () => validateSelectors,
+  validateSource: () => import_weather4.validateSource,
+  version: () => version,
+  weather: () => weather
+});
+module.exports = __toCommonJS(index_exports);
+var import_core3 = require("@mostlyrightmd/core");
+var import_weather3 = require("@mostlyrightmd/weather");
+var import_markets2 = require("@mostlyrightmd/markets");
+var core = __toESM(require("@mostlyrightmd/core"), 1);
+var markets = __toESM(require("@mostlyrightmd/markets"), 1);
+var weather = __toESM(require("@mostlyrightmd/weather"), 1);
+
+// src/research.ts
+var import_core = require("@mostlyrightmd/core");
+var import_cache = require("@mostlyrightmd/core/internal/cache");
+var import_merge = require("@mostlyrightmd/core/internal/merge");
+var import_pairs = require("@mostlyrightmd/core/internal/pairs");
+var import_weather = require("@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 (0, import_cache.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 = import_core.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 = import_core.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 = import_core.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 (0, import_core.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 (0, import_cache.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 (0, import_cache.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 = (0, import_cache.isWritableYear)(year, now);
+    const skipCurrentYear = (0, import_cache.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((0, import_cache.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 (0, import_weather.downloadCliRange)(fetchIcao, year, year, cliOpts);
+    const parsed = (0, import_weather.parseCliResponse)(cliRaw, cacheCode);
+    acc.push(...parsed);
+    const sample = parsed[0]?.source;
+    if (cache !== null && !skip && !(0, import_cache.isLiveSource)(sample)) {
+      try {
+        await cache.set((0, import_cache.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 (0, import_weather.downloadIemAsos)(stationCode, `${year}-01-01`, `${year}-12-31`, iemOpts);
+    const fetched = [];
+    for (const chunk of chunks) {
+      const parsed = (0, import_weather.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 = (0, import_cache.cacheKeyForObservations)(stationCode, year, month, "iem");
+    const writable = (0, import_cache.isWritableMonth)(year, month, now);
+    const skipCurrentMonth = (0, import_cache.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 && !(0, import_cache.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 (0, import_weather.downloadGhcnh)(ghcnhId, year, ghcnhOpts);
+      parsed = (0, import_weather.parseGhcnhPsv)(yr.psv);
+    } catch (err) {
+      if (err instanceof import_core.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 = (0, import_cache.cacheKeyForObservations)(stationCode, year, month, "ghcnh");
+    const writable = (0, import_cache.isWritableMonth)(year, month, now);
+    const skipCurrentMonth = (0, import_cache.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 && !(0, import_cache.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 = (0, import_merge.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 (0, import_weather.fetchAwcMetars)([resolved.icao], awcOpts);
+    for (const m of awcRaw) {
+      const obs = (0, import_weather.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 = (0, import_merge.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 (0, import_pairs.buildPairs)(resolved.code, dates, observationsByDate, climateByDate);
+}
+
+// src/mode2.ts
+var import_core2 = require("@mostlyrightmd/core");
+var import_weather2 = require("@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 import_core2.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 = import_core2.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,
+      country: byIcao.country,
+      ghcnhId: byIcao.ghcnh_id
+    };
+  }
+  const byCode = import_core2.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,
+      country: byCode.country,
+      ghcnhId: byCode.ghcnh_id
+    };
+  }
+  if (raw.startsWith("K") && raw.length === 4) {
+    const stripped = raw.slice(1);
+    const retry = import_core2.STATION_BY_CODE.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 (0, import_weather2.fetchAwcMetars)([resolved.icao], awcOpts);
+      const parsed = [];
+      for (const m of raw) {
+        const obs = (0, import_weather2.awcToObservation)(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 (0, import_weather2.downloadIemAsos)(
+            resolved.code,
+            `${year}-01-01`,
+            `${year}-12-31`,
+            iemOpts
+          );
+          for (const chunk of chunks) {
+            const parsed = (0, import_weather2.parseIemCsv)(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 import_core2.NotFoundError(
+          `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 (0, import_weather2.downloadGhcnh)(resolved.ghcnhId, year, ghcnhOpts);
+          const parsed = (0, import_weather2.parseGhcnhPsv)(yr.psv);
+          for (const r of parsed) {
+            if (r.station_code === resolved.code) collected.push(r);
+          }
+        } catch (err) {
+          if (err instanceof import_core2.NotFoundError) 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
+var import_markets = require("@mostlyrightmd/markets");
+var import_polymarket = require("@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 = import_markets.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 = import_markets.KALSHI_SETTLEMENT_STATIONS[kalshiSlug];
+  if (kalshi !== void 0 && !out.includes(kalshi.station)) {
+    out.push(kalshi.station);
+  }
+  const poly = import_markets.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 = import_polymarket.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 = import_markets.KALSHI_SETTLEMENT_STATIONS[kalshiSlug];
+  if (kalshi !== void 0 && kalshi.station === station) {
+    out.push(`kalshi:${kalshiSlug}`);
+  }
+  const poly = import_markets.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
+var import_weather4 = require("@mostlyrightmd/weather");
+var import_core4 = require("@mostlyrightmd/core");
+var version = "0.0.0";
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  LiveStreamError,
+  MODE2_SOURCES,
+  NoLiveDataError,
+  POLITE_FLOORS_S,
+  SELECTOR_NAMES,
+  SOURCE_ALIASES,
+  SOURCE_IDENTITY_TAGS,
+  SUPPORTED_SOURCES,
+  annotateSettlesFor,
+  assertSourceIdentity,
+  buildOverrideWarning,
+  core,
+  discover,
+  helloCore,
+  helloMarkets,
+  helloWeather,
+  isLiveSource,
+  isMode2Source,
+  latest,
+  markets,
+  research,
+  researchBySource,
+  resolveCity,
+  resolveContract,
+  sourceTag,
+  stream,
+  validatePollSeconds,
+  validateSelectors,
+  validateSource,
+  version,
+  weather
+});
+//# sourceMappingURL=index.cjs.map