mostlyrightmd 0.1.0__py3-none-any.whl

mostlyright/__init__.py

@@ -0,0 +1,46 @@
+"""mostlyright — local-first SDK for prediction-market weather settlement research.
+
+Sprint 0 v0.1.0 ships:
+- ``mostlyright.research(station, from_date, to_date, ...)`` — the v0.14.1 ``pairs()`` join,
+  lifted from monorepo-v0.14.1, calling AWC + IEM + GHCNh + NWS CLI directly.
+- ``mostlyright.snapshot`` — settlement-window math (LST, market_close_utc).
+
+Adjacent surfaces:
+- ``mostlyright.weather`` — observations + climate + forecasts (sibling package ``mostlyrightmd-weather``).
+- ``mostlyright.markets`` — Kalshi + Polymarket metadata (sibling package ``mostlyrightmd-markets``,
+  ships v0.1.0 in Sprint 0.5).
+
+Namespace note: ``mostlyright`` is a split-distribution namespace package. Core owns this
+``__init__.py``; sibling distributions ``mostlyrightmd-weather`` and ``mostlyrightmd-markets`` ship
+subdirectories (``mostlyright/weather/``, ``mostlyright/markets/``) WITHOUT their own
+namespace-root ``__init__.py``. The pkgutil declaration below extends ``__path__`` so Python's
+import machinery finds those subpackages from whichever site-packages location installed them.
+"""
+
+# Split-distribution namespace: extend __path__ to discover sibling packages' contributions.
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)
+
+__version__ = "0.1.0rc1"
+
+from mostlyright.discover import discover
+from mostlyright.research import research
+
+__all__ = ["__version__", "discover", "live", "research"]
+
+
+# Lazy `mostlyright.live` access (Phase 11). Both `discover` and `research`
+# above already eagerly import `mostlyright.core` (which pulls pandas via
+# `core.validator`), so the eager-pandas path is pre-existing and NOT a
+# Phase 11 regression. Even so, we expose `live` through a module-level
+# `__getattr__` hook so `import mostlyright` doesn't pull in
+# `mostlyright.weather` (via the live module's deferred fetcher imports
+# that fire on first use, not first attribute access). First access via
+# `mostlyright.live.stream(...)` resolves and caches the submodule.
+def __getattr__(name: str):
+    if name == "live":
+        import mostlyright.live as _live
+
+        # Cache on the module so subsequent accesses skip __getattr__.
+        globals()["live"] = _live
+        return _live
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

mostlyright/_compose.py

@@ -0,0 +1,338 @@
+"""Phase 10 — composable ``research()`` dispatcher.
+
+Translates the new selectors (``city=``, ``contract=``, ``contracts=``)
+into resolution metadata + station tuples that the existing
+station-based ``research()`` machinery consumes. Cross-issuer annotation
+(``settles_for``) is computed here so the dispatch layer is the single
+source of truth for "which markets settle against which stations."
+
+The dispatcher is intentionally pure (no I/O, no DataFrame
+construction) so unit tests run instantly and the same logic can be
+reused by ``discover()`` and the TS counterpart.
+"""
+
+from __future__ import annotations
+
+import warnings
+from typing import Any
+
+#: The valid selector kwarg names. Exactly one must be provided on each
+#: ``research()`` invocation; passing zero or >1 raises ``ValueError``.
+_SELECTOR_NAMES: tuple[str, ...] = ("station", "city", "contract", "contracts")
+
+
+#: Kalshi short-ticker → canonical city slug. Real Kalshi tickers use
+#: variable-length city suffixes: ``KXHIGHNY-...`` (NY → NYC),
+#: ``KXHIGHCHI-...`` (CHI → CHI), ``KXHIGHLAX-...`` (LAX → LAX). The
+#: ``KALSHI_SETTLEMENT_STATIONS`` catalog is keyed by the canonical
+#: 3-letter city slug; this alias table normalizes the variable-length
+#: Kalshi suffix to the catalog key before lookup. Phase 10 iter-1 codex
+#: HIGH: without this, ``kalshi:KXHIGHNY-25MAY26-T79`` (the actual
+#: ROADMAP example) would fail to resolve.
+_KALSHI_TICKER_ALIASES: dict[str, str] = {
+    "NY": "NYC",
+    # All other Kalshi cities use the canonical 3-letter slug as their
+    # ticker suffix verbatim (identity mapping is implicit).
+}
+
+
+#: Kalshi-short ↔ Polymarket-long city slug alias. Architect iter-1 HIGH:
+#: ``resolve_city`` and ``annotate_settles_for`` need to recognize BOTH
+#: forms so a single call with EITHER input surfaces the cross-issuer
+#: settlement neighborhood. Without this, ``resolve_city("LAX")`` would
+#: miss Polymarket's KLAX entry (Polymarket keys it as ``los_angeles``);
+#: ``resolve_city("chicago")`` would miss Kalshi's KMDW (Kalshi keys it
+#: as ``CHI``). Bi-directional table — looked up either way.
+_CITY_SLUG_ALIASES: dict[str, tuple[str, str]] = {
+    # short_kalshi: (long_polymarket, canonical_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"),
+}
+
+# Build reverse lookup so passing the Polymarket long form also surfaces
+# the Kalshi short form.
+_CITY_SLUG_ALIASES_REVERSE: dict[str, tuple[str, str]] = {
+    long_poly: (short_kalshi, kalshi_upper)
+    for short_kalshi, (long_poly, kalshi_upper) in _CITY_SLUG_ALIASES.items()
+}
+
+
+def _normalize_city_slugs(city: str) -> tuple[str, str]:
+    """Return ``(polymarket_slug_lower, kalshi_slug_upper)`` for ``city``.
+
+    Accepts either form (``"nyc"`` or ``"NYC"``, ``"chicago"`` or ``"CHI"``)
+    and returns both canonical forms so callers can probe either catalog.
+
+    Falls back to ``(city.lower(), city.upper())`` for cities not in the
+    alias table (international cities the user might pass).
+    """
+    lower = city.lower()
+    upper = city.upper()
+    if lower in _CITY_SLUG_ALIASES:
+        long_poly, kalshi_upper = _CITY_SLUG_ALIASES[lower]
+        return long_poly, kalshi_upper
+    if lower in _CITY_SLUG_ALIASES_REVERSE:
+        short_kalshi, kalshi_upper = _CITY_SLUG_ALIASES_REVERSE[lower]
+        return lower, kalshi_upper
+    return lower, upper
+
+
+class StationOverrideWarning(UserWarning):
+    """Emitted when ``station_override=`` deliberately mismatches the
+    contract's canonical settlement station.
+
+    The output row carries ``settlement_mismatch=True`` so downstream
+    backtest code can filter / flag these silently-divergent rows.
+    """
+
+
+def validate_selectors(
+    *,
+    station: str | None = None,
+    city: str | None = None,
+    contract: str | None = None,
+    contracts: list[str] | tuple[str, ...] | None = None,
+) -> str:
+    """Validate that exactly one selector is provided; return the active name.
+
+    Args:
+        station, city, contract, contracts: the four mutually-exclusive
+            selectors. Exactly one must be non-None / non-empty.
+
+    Returns:
+        The name of the active selector (``"station"`` / ``"city"`` /
+        ``"contract"`` / ``"contracts"``).
+
+    Raises:
+        ValueError: zero or >1 selectors provided.
+    """
+    provided: list[str] = []
+    if station is not None and station != "":
+        provided.append("station")
+    if city is not None and city != "":
+        provided.append("city")
+    if contract is not None and contract != "":
+        provided.append("contract")
+    if contracts is not None and len(contracts) > 0:
+        provided.append("contracts")
+    if not provided:
+        raise ValueError(
+            "research(): exactly one of station=, city=, contract=, contracts= must be provided"
+        )
+    if len(provided) > 1:
+        raise ValueError(f"research(): selectors are mutually exclusive; got {provided!r}")
+    return provided[0]
+
+
+def resolve_contract(contract_id: str) -> tuple[str, str]:
+    """Resolve a ``"<issuer>:<id>"`` string to ``(station, issuer)``.
+
+    Supported issuers:
+    - ``kalshi:`` — ``KHIGH*``/``KXHIGH*``/``KLOW*``/``KXLOW*`` city tickers.
+    - ``polymarket:`` — event/market ids. v0.2 raises NotImplementedError
+      with an actionable message (the resolver lives in
+      :mod:`mostlyright.markets._per_event_station` but requires a fetched
+      event payload to identify the city; Phase 10 v0.2 surfaces this as
+      a clear error and defers the integration to v0.3).
+
+    Args:
+        contract_id: ``"<issuer>:<id>"`` string (e.g.
+            ``"kalshi:KXHIGHNYC"`` or ``"polymarket:0x..."``).
+
+    Returns:
+        Tuple of ``(station_icao, issuer_name)``.
+
+    Raises:
+        ValueError: malformed contract id or unknown issuer.
+        NotImplementedError: Polymarket contract resolution (deferred).
+    """
+    if not isinstance(contract_id, str) or ":" not in contract_id:
+        raise ValueError(f"contract id must be `<issuer>:<id>`; got {contract_id!r}")
+    issuer, raw = contract_id.split(":", 1)
+    issuer = issuer.lower()
+    raw_upper = raw.upper()
+    if issuer == "kalshi":
+        from datetime import date as _date
+
+        from mostlyright.markets.catalog import kalshi_nhigh, kalshi_nlow
+
+        # Kalshi tickers come in two prefix families:
+        #   KHIGH<CITY>* / KXHIGH<CITY>* → NHIGH (daily-high)
+        #   KLOW<CITY>*  / KXLOW<CITY>*  → NLOW (daily-low)
+        # The existing kalshi_nhigh / kalshi_nlow resolvers were built for
+        # the legacy KHIGH<CITY> / KLOW<CITY> shape. Modern Kalshi market
+        # tickers use the KX-prefix exchange convention
+        # (KXHIGH<CITY>-<DATE>-<STRIKE>); strip the `KX` to feed the
+        # resolver and pass the bare city portion. The resolver's own
+        # validation (`startswith("KHIGH")` / `startswith("KLOW")` +
+        # length>5) does the city-ticker validity check.
+        # Strip just the 'X' from the KX exchange prefix so KXHIGH<CITY>
+        # becomes KHIGH<CITY> (the legacy resolver's expected format).
+        # KX = position [0..1] but the literal 'K' is kept; drop position [1].
+        normalized = raw_upper
+        if normalized.startswith("KX"):
+            normalized = "K" + normalized[2:]  # KXHIGHNYC → KHIGHNYC
+        # Many full Kalshi tickers carry a trailing -DATE-STRIKE suffix
+        # (e.g. KXHIGHNYC-25MAY26-T79 → KXHIGHNYC). Pull the city portion
+        # by trimming at the first '-'.
+        city_only = normalized.split("-", 1)[0]
+        # Extract the variable-length city suffix and normalize via the
+        # Kalshi-ticker alias table so KXHIGHNY → NY → NYC (the canonical
+        # catalog key). Iter-1 codex HIGH.
+        if city_only.startswith("KHIGH") and len(city_only) > 5:
+            short = city_only[5:]
+            canonical = _KALSHI_TICKER_ALIASES.get(short, short)
+            r = kalshi_nhigh.resolve(f"KHIGH{canonical}", _date.today())
+            return r.settlement_station, "kalshi"
+        if city_only.startswith("KLOW") and len(city_only) > 4:
+            short = city_only[4:]
+            canonical = _KALSHI_TICKER_ALIASES.get(short, short)
+            r = kalshi_nlow.resolve(f"KLOW{canonical}", _date.today())
+            return r.settlement_station, "kalshi"
+        raise ValueError(
+            f"unsupported kalshi contract format: {raw!r}; "
+            "expected KHIGH<CITY>* / KXHIGH<CITY>* / KLOW<CITY>* / "
+            "KXLOW<CITY>* prefix"
+        )
+    if issuer == "polymarket":
+        raise NotImplementedError(
+            "polymarket contract resolution requires event_id → station lookup "
+            "via polymarket_discover() or polymarket_settle(); Phase 10 v0.2 "
+            "defers this integration to v0.3. Use `city='nyc'` or pass the "
+            "station explicitly via `station_override=` until then."
+        )
+    raise ValueError(f"unknown issuer prefix: {issuer!r}; expected kalshi or polymarket")
+
+
+def resolve_city(city: str) -> tuple[str, ...]:
+    """Resolve a city slug to all stations any issuer settles against.
+
+    Returns a deduplicated tuple in stable order:
+      1. Kalshi's settlement station (if the city is in the Kalshi catalog).
+      2. Polymarket's default + high + low stations (if in Polymarket catalog).
+      3. Polymarket per-city denylist entries (forbidden-but-known stations
+         surfaced so quants can SEE the full neighborhood for explicit
+         ``station_override=``).
+
+    For ``"NYC"`` returns (``"KNYC"``, ``"KLGA"``, ``"KJFK"``, ``"KEWR"``)
+    — KNYC is Kalshi's, KLGA is Polymarket's, KJFK + KEWR are the
+    denylist backstops Polymarket forbids.
+
+    Args:
+        city: city slug. Accepts ``"NYC"`` (Kalshi upper) or ``"nyc"``
+            (Polymarket lower); both are normalized.
+
+    Returns:
+        Tuple of station ICAOs.
+
+    Raises:
+        ValueError: city not in either catalog.
+    """
+    if not isinstance(city, str) or not city:
+        raise ValueError(f"city must be a non-empty str; got {city!r}")
+
+    from mostlyright.markets._per_event_station import load_polymarket_city_stations
+    from mostlyright.markets.catalog.kalshi_stations import (
+        KALSHI_SETTLEMENT_STATIONS,
+    )
+    from mostlyright.markets.polymarket import KNOWN_WRONG_STATIONS as POLY_WRONG
+
+    # Iter-1 python-architect HIGH: normalize via the cross-issuer slug
+    # alias table so a single call (with either "NYC" or "nyc", "CHI" or
+    # "chicago", "LAX" or "los_angeles") surfaces the full cross-issuer
+    # settlement neighborhood from BOTH catalogs.
+    poly_slug, kalshi_slug = _normalize_city_slugs(city)
+    out: list[str] = []
+    if kalshi_slug in KALSHI_SETTLEMENT_STATIONS:
+        out.append(KALSHI_SETTLEMENT_STATIONS[kalshi_slug].station)
+    poly = load_polymarket_city_stations()
+    if poly_slug in poly:
+        # Preserve insertion order across the measure keys.
+        for measure in ("default", "high", "low"):
+            st = poly[poly_slug].get(measure)
+            if st and st not in out:
+                out.append(st)
+    for st in sorted(POLY_WRONG.get(poly_slug, frozenset())):
+        if st not in out:
+            out.append(st)
+    if not out:
+        raise ValueError(f"unknown city {city!r}; not in kalshi or polymarket catalogs")
+    return tuple(out)
+
+
+def annotate_settles_for(station: str, city: str | None) -> list[str]:
+    """Return the list of ``"<issuer>:<ticker>"`` markers that settle
+    against ``station`` for ``city``.
+
+    Empty list means no known issuer settles against this station for
+    this city (typically a denylist entry surfaced by
+    :func:`resolve_city` for the caller's awareness).
+
+    Args:
+        station: 4-char K-prefix ICAO.
+        city: city slug (optional; when None, returns empty list).
+
+    Returns:
+        Sorted list of ``"kalshi:CITY"`` / ``"polymarket:city"`` markers.
+    """
+    out: list[str] = []
+    if city is None:
+        return out
+    from mostlyright.markets._per_event_station import load_polymarket_city_stations
+    from mostlyright.markets.catalog.kalshi_stations import (
+        KALSHI_SETTLEMENT_STATIONS,
+    )
+
+    # Iter-1 python-architect HIGH: use cross-issuer slug alias so the
+    # annotation works regardless of which slug-form the caller passed.
+    poly_slug, kalshi_slug = _normalize_city_slugs(city)
+    if (
+        kalshi_slug in KALSHI_SETTLEMENT_STATIONS
+        and KALSHI_SETTLEMENT_STATIONS[kalshi_slug].station == station
+    ):
+        out.append(f"kalshi:{kalshi_slug}")
+    poly = load_polymarket_city_stations()
+    if poly_slug in poly and station in poly[poly_slug].values():
+        out.append(f"polymarket:{poly_slug}")
+    return sorted(out)
+
+
+def emit_override_warning(contract_station: str, override_station: str) -> None:
+    """Helper: emit :class:`StationOverrideWarning` for a deliberate mismatch."""
+    warnings.warn(
+        f"station_override={override_station!r} differs from contract's "
+        f"canonical settlement station {contract_station!r}; output row will "
+        f"carry settlement_mismatch=True",
+        StationOverrideWarning,
+        stacklevel=3,
+    )
+
+
+__all__ = [
+    "StationOverrideWarning",
+    "annotate_settles_for",
+    "emit_override_warning",
+    "resolve_city",
+    "resolve_contract",
+    "validate_selectors",
+]
+
+
+# Silence the `Any` import warning — kept for ruff future-proofing if/when
+# the dispatch layer needs to type DataFrame returns.
+_ = Any

mostlyright/_exact_fetch.py

@@ -0,0 +1,162 @@
+"""Exact-window obs fetcher — bypasses year-aligned monthly cache.
+
+Used by `mostlyright.weather.obs(strategy="exact_window")` to serve small,
+caller-bounded windows (e.g. 1-month backtest replays) without pulling a
+full calendar year of IEM CSV.
+
+DOES NOT WRITE to the canonical `observations/{STATION}/{YYYY}/{MM}.parquet`
+cache — exact_window queries are treated as transient. Callers who need
+warm-cache speedups for repeated calls should use `strategy="warm_cache"`.
+
+Source filtering is enforced at the FETCHER BOUNDARY (not post-merge):
+post-merge filtering would silently drop rows where the named source lost
+the priority tie to a HIGHER-priority source that this call also fetched.
+By gating each fetcher behind `source in (None, "<name>")`, the merge sees
+only rows from the requested source(s) and the priority resolution is
+semantically correct.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, date, datetime, timedelta
+from typing import TYPE_CHECKING, Any, Literal
+
+from mostlyright._internal.merge import merge_observations
+from mostlyright.weather._awc import awc_to_observation
+from mostlyright.weather._fetchers.awc import fetch_awc_metars
+from mostlyright.weather._fetchers.ghcnh import download_ghcnh
+from mostlyright.weather._fetchers.iem_asos import download_iem_asos
+from mostlyright.weather._ghcnh import parse_ghcnh_file
+from mostlyright.weather._iem import parse_iem_file
+
+if TYPE_CHECKING:
+    from mostlyright._internal.models.station import StationInfo
+
+
+Source = Literal["iem", "ghcnh", "awc"]
+
+
+def _exact_fetch_observations(
+    info: StationInfo,
+    from_date_iso: str,
+    to_date_iso: str,
+    *,
+    source: Source | None = None,
+) -> list[dict[str, Any]]:
+    """Fetch obs rows for the exact [from_date, to_date] window.
+
+    Skips year-normalization in IEM by passing ``exact_window=True`` to
+    ``download_iem_asos``. Does NOT write to the canonical monthly parquet cache.
+
+    Parameters
+    ----------
+    info : StationInfo
+        Resolved station metadata (icao, code, ghcnh_id, ...).
+    from_date_iso, to_date_iso : str
+        ISO YYYY-MM-DD strings, inclusive bounds for the obs window.
+    source : {"iem", "ghcnh", "awc"} | None
+        If set, only that source is queried (fetcher-boundary enforcement).
+        If None, all three are queried and merged via SOURCE_PRIORITY in
+        ``mostlyright._internal.merge.observations`` (AWC > IEM > GHCNh).
+
+    Returns
+    -------
+    list[dict]
+        Merged observation rows for the window. NOT cached to canonical
+        monthly parquet; callers wanting cache benefit should use
+        ``strategy="warm_cache"``.
+    """
+    # Local import: research depends on weather, but _exact_fetch only needs
+    # the _sources_root helper for path layout — keep the dependency one-way
+    # by importing inside the function.
+    from mostlyright.research import _sources_root
+
+    from_date = date.fromisoformat(from_date_iso)
+    to_date = date.fromisoformat(to_date_iso)
+    # Mirror research.py:1167 — extend by 1 day to capture the pre-midnight
+    # UTC tail of the last LST settlement window.
+    extended_to = to_date + timedelta(days=1)
+
+    sources_root = _sources_root()
+    rows: list[dict[str, Any]] = []
+
+    # --- IEM ASOS ----------------------------------------------------------
+    # Fetcher-boundary enforcement: skip IEM entirely if caller asked for a
+    # different source. Separate dest_dir namespace (per B-5) — exact-window
+    # CSVs live in `sources/iem_asos_exact/`, NEVER in `sources/iem_asos/`.
+    if source in (None, "iem"):
+        iem_exact_dir = sources_root / "iem_asos_exact"
+        # IEM has two report types: 3 (METAR) and 4 (SPECI). Mirror the
+        # canonical _fetch_iem_month behavior so the merge sees both.
+        for report_type, override in ((3, "METAR"), (4, "SPECI")):
+            paths = download_iem_asos(
+                info,
+                from_date,
+                extended_to,
+                iem_exact_dir,
+                report_type=report_type,
+                exact_window=True,
+            )
+            for p in paths:
+                rows.extend(parse_iem_file(p, observation_type_override=override))
+
+    # --- AWC METAR (live 168h only) ---------------------------------------
+    # ``fetch_awc_metars`` is live-only — no date range. If ``to_date`` is older
+    # than ``now - 168h``, AWC will return zero rows for the window. Skip the
+    # HTTP call in that case. We DO NOT filter rows by UTC date here — the
+    # final aggregation layer in obs.py buckets by LST settlement_date, which
+    # correctly captures the post-midnight-UTC tail of the last LST day for
+    # negative-offset US stations (codex iter-1 CRITICAL #2).
+    if source in (None, "awc"):
+        now_utc = datetime.now(UTC)
+        awc_horizon = now_utc.date() - timedelta(days=7)
+        if to_date >= awc_horizon:
+            raw_metars = fetch_awc_metars([info.icao], hours=168)
+            for m in raw_metars:
+                obs = awc_to_observation(m)
+                if obs is None:
+                    continue
+                # Defensive: AWC may serve unrelated stations from cached
+                # responses. Drop those; let settlement-date bucketing handle
+                # window filtering downstream.
+                if obs.get("station_code") != info.code:
+                    continue
+                rows.append(obs)
+
+    # --- GHCNh (per-station-year) -----------------------------------------
+    if source in (None, "ghcnh"):
+        import httpx
+
+        from mostlyright.weather.cache import _is_current_lst_year
+
+        ghcnh_dir = sources_root / "ghcnh"
+        # Per-station-year files; iterate calendar years touching the window.
+        # Mirror research.py:_fetch_ghcnh_year mutable-period gate: NCEI
+        # republishes the current LST year's PSV as new months land, so
+        # callers MUST force a re-download for that year (codex iter-1 HIGH).
+        for year in range(from_date.year, extended_to.year + 1):
+            skip_cache = _is_current_lst_year(info.icao, year)
+            try:
+                psv_path = download_ghcnh(info.ghcnh_id, year, ghcnh_dir, skip_cache=skip_cache)
+            except httpx.HTTPStatusError as exc:
+                # NCEI returns 404 for stations without data; mirror
+                # _fetch_ghcnh_year's graceful skip.
+                if exc.response.status_code == 404:
+                    continue
+                raise
+            for row in parse_ghcnh_file(psv_path):
+                if row.get("station_code") != info.code:
+                    continue
+                rows.append(row)
+
+    # Pre-sort by (observed_at, source) BEFORE merge — mirrors research.py R2
+    # mitigation. merge_observations uses first-seen-wins at equal priority
+    # and returns `list(best.values())` in dict-insertion order, so input
+    # order is load-bearing for both tie-break determinism AND survivor order.
+    rows.sort(key=lambda r: (r.get("observed_at") or "", r.get("source") or ""))
+
+    # merge_observations takes a single positional list, NO source_priority kwarg.
+    # Priority is hard-coded via SOURCE_PRIORITY in the merge module. Source
+    # filtering already happened at the fetcher boundary above — do NOT
+    # post-filter merged rows by source.
+    return merge_observations(rows)

mostlyright/_internal/__init__.py

@@ -0,0 +1,31 @@
+"""mostlyright._internal — shared utilities lifted from monorepo-v0.14.1.
+
+NOT a public API. Module names start with underscore to discourage downstream
+use; rely on ``mostlyright.research()`` / ``mostlyright.snapshot.*`` instead.
+
+Lift inventory (provenance for parity-critical code). Source SHA refers to the
+v0.14.1 release tag of ``Tarabcak/monorepo`` (commit
+``514fcdab227e845145ca32b989355647466231d9``); ``_pairs.py`` additionally
+pins the exact source-file blob SHA from that tree.
+
+| Module                | Source path                                              | Source SHA   | Lift date  | Modifications                                                          |
+|-----------------------|----------------------------------------------------------|--------------|------------|------------------------------------------------------------------------|
+| _http.py              | monorepo-v0.14.1/src/mostlyright/_http.py                | 514fcda      | 2026-05-21 | namespace rename only (mostlyright -> mostlyright._internal)            |
+| _convert.py           | monorepo-v0.14.1/src/mostlyright/_convert.py             | 514fcda      | 2026-05-21 | namespace rename only                                                  |
+| _bounds.py            | monorepo-v0.14.1/src/mostlyright/_bounds.py              | 514fcda      | 2026-05-21 | namespace rename only                                                  |
+| _capabilities.py      | monorepo-v0.14.1/src/mostlyright/_capabilities.py        | 514fcda      | 2026-05-21 | namespace rename only                                                  |
+| _toon.py              | monorepo-v0.14.1/src/mostlyright/_toon.py                | 514fcda      | 2026-05-22 | ruff-clean RUF002/003 (replace EN DASH in inline comments); body identical |
+| exceptions.py         | monorepo-v0.14.1/src/mostlyright/exceptions.py           | 514fcda      | 2026-05-21 | namespace rename only                                                  |
+| versioning.py         | monorepo-v0.14.1/src/mostlyright/versioning.py           | 514fcda      | 2026-05-21 | namespace rename only                                                  |
+| models/               | monorepo-v0.14.1/src/mostlyright/models/                 | 514fcda      | 2026-05-21 | namespace rename only                                                  |
+| specs/*.json          | monorepo-v0.14.1/src/mostlyright/specs/                  | 514fcda      | 2026-05-21 | none (data-only)                                                       |
+| _stations.py          | monorepo-v0.14.1/src/mostlyright/_stations.py            | 514fcda      | 2026-05-22 | none (pure-data module; no imports to rename)                          |
+| _pairs.py             | monorepo-v0.14.1/src/mostlyright/pairs.py                | e78eed5 (blob, in tree 514fcda) | 2026-05-22 | TOON imports + ``to_toon`` function excised; namespace rename          |
+| merge/observations.py | monorepo-v0.14.1/ingest/storage/parquet.py:47-48,246-261 | 514fcda      | 2026-05-21 | rename ``_dedup_rows`` -> ``merge_observations`` (public API)          |
+| merge/climate.py      | monorepo-v0.14.1/ingest/storage/parquet.py:477-494       | 514fcda      | 2026-05-21 | rename ``_dedup_climate_rows`` -> ``merge_climate`` (public API)       |
+| merge/_schemas.py     | monorepo-v0.14.1/ingest/storage/parquet.py:50-103        | 514fcda      | 2026-05-21 | none (verbatim lift; field order + dtypes preserved)                   |
+
+Any drift in ``merge/`` or ``_pairs.py`` invalidates every historical Kalshi
+NHIGH/NLOW settlement — treat as load-bearing and re-run the parity gate
+(``tests/test_parity.py``) before merging changes here.
+"""