mostlyright 0.1.0-rc.7

package/dist/index.d.ts

@@ -0,0 +1,295 @@
+import { SourceMismatchRole } from '@mostlyrightmd/core';
+import * as core from '@mostlyrightmd/core';
+export { core };
+export { LiveStreamError, NoLiveDataError, SourceMismatchRole, helloCore } from '@mostlyrightmd/core';
+import { Observation } from '@mostlyrightmd/weather';
+import * as weather from '@mostlyrightmd/weather';
+export { weather };
+export { LatestOptions, LiveObservation, LiveSource, LiveSourceTag, POLITE_FLOORS_S, SOURCE_IDENTITY_TAGS, SUPPORTED_SOURCES, StreamOptions, helloWeather, isLiveSource, latest, sourceTag, stream, validatePollSeconds, validateSource } from '@mostlyrightmd/weather';
+import * as markets from '@mostlyrightmd/markets';
+export { markets };
+export { helloMarkets } from '@mostlyrightmd/markets';
+import { CacheStore } from '@mostlyrightmd/core/internal/cache';
+import { PairsRow } from '@mostlyrightmd/core/internal/pairs';
+export { PairsRow } from '@mostlyrightmd/core/internal/pairs';
+
+/** The four mutually-exclusive selector names. */
+declare const SELECTOR_NAMES: readonly ["station", "city", "contract", "contracts"];
+type SelectorName = (typeof SELECTOR_NAMES)[number];
+/**
+ * Structured warning emitted when `stationOverride` deliberately
+ * mismatches the contract's canonical settlement station. The output
+ * row carries `settlementMismatch: true`.
+ *
+ * JS has no `warnings.warn()` analogue; callers receive these via the
+ * `onWarning?` callback in ResearchOptions.
+ */
+interface StationOverrideWarning {
+    readonly kind: "StationOverrideWarning";
+    readonly contractStation: string;
+    readonly overrideStation: string;
+    readonly message: string;
+}
+/** Selector kwargs accepted by research(). Exactly one MUST be provided. */
+interface SelectorArgs {
+    readonly station?: string;
+    readonly city?: string;
+    readonly contract?: string;
+    readonly contracts?: ReadonlyArray<string>;
+}
+/**
+ * Validate selector arity. Returns the active selector name; throws when
+ * zero or >1 selectors are provided.
+ */
+declare function validateSelectors(args: SelectorArgs): SelectorName;
+/**
+ * Resolve a `"<issuer>:<id>"` contract id to `[station, issuer]`.
+ *
+ * Supported: `kalshi:KHIGH<CITY>` / `kalshi:KXHIGH<CITY>-<DATE>-<STRIKE>`
+ * and `kalshi:KLOW<CITY>` / `kalshi:KXLOW<CITY>-<DATE>-<STRIKE>`.
+ *
+ * Polymarket contract resolution requires an event_id → station lookup
+ * (via polymarket-discover); Phase 10 v0.2 defers to v0.3 and throws.
+ */
+declare function resolveContract(contractId: string): readonly [string, string];
+/**
+ * Resolve a city slug to all stations any issuer settles against.
+ * Returns deduplicated array in stable order: Kalshi → Polymarket default/high/low
+ * → Polymarket denylist backstops.
+ */
+declare function resolveCity(city: string): readonly string[];
+/**
+ * Return the list of `"<issuer>:<ticker>"` markers that settle against
+ * `station` for `city`. Empty array when no issuer settles against this
+ * station (typically a denylist backstop).
+ */
+declare function annotateSettlesFor(station: string, city: string | null): readonly string[];
+/**
+ * Build a structured `StationOverrideWarning` payload. Callers receive
+ * these via the optional `onWarning?` callback on research options.
+ */
+declare function buildOverrideWarning(contractStation: string, overrideStation: string): StationOverrideWarning;
+
+interface ResearchOptions {
+    /** Forward to all underlying fetchers; aborts the whole pipeline. */
+    signal?: AbortSignal;
+    /** AWC lookback window in hours. Default 168 (AWC max). Clamped by the fetcher. */
+    awcHours?: number;
+    /** Polite-delay (ms) between successive IEM ASOS year chunks. Default 1000. */
+    iemPolitenessMs?: number;
+    /** Polite-delay (ms) between successive GHCNh year requests. Default 1000. */
+    ghcnhPolitenessMs?: number;
+    /** Polite-delay (ms) between successive CLI year requests. Default 1000. */
+    cliPolitenessMs?: number;
+    /**
+     * Reference clock for the AWC-window overlap check (test-only seam).
+     * Defaults to `new Date()`. Pass an override to force-include AWC for
+     * historical date ranges in unit tests.
+     */
+    now?: Date;
+    /**
+     * Pluggable cache backend (TS-W3). When omitted, uses
+     * `defaultCacheStore()` (auto-detects IndexedDB → FsStore → MemoryStore).
+     * Pass `null` to opt out of caching entirely.
+     */
+    cache?: CacheStore | null;
+    /** Cross-issuer city selector. Returns rows for every station that any
+     *  issuer settles against (Kalshi + Polymarket + denylist backstops). */
+    city?: string;
+    /** Single-contract selector. Format: `"<issuer>:<id>"` (e.g.
+     *  `"kalshi:KXHIGHNYC-25MAY26-T79"`). Auto-resolves to the contract's
+     *  canonical settlement station via the Phase 8 catalog. */
+    contract?: string;
+    /** Multi-contract selector for basis-trade research. */
+    contracts?: ReadonlyArray<string>;
+    /** Override the contract's canonical settlement station. Emits a
+     *  StationOverrideWarning via `onWarning?`; output row carries
+     *  `settlementMismatch: true`. Only valid with `contract` selector. */
+    stationOverride?: string;
+    /** Mode 1 source subset — dedupe within. Mutually exclusive with `source`. */
+    sources?: ReadonlyArray<string>;
+    /** Mode 2 single-source pin — error on mismatch. Mutually exclusive with `sources`. */
+    source?: string;
+    /** Attach per-issuer trade timeseries via @mostlyrightmd/markets/trades.
+     *  Requires `contract` or `contracts`. */
+    includeTrades?: boolean;
+    /** Callback receiving Phase 10 StationOverrideWarning (no `warnings.warn()`
+     *  analogue in JS). */
+    onWarning?: (w: StationOverrideWarning) => void;
+}
+/**
+ * Build daily research rows for a station + date window.
+ *
+ * @param station NWS 3-letter code (e.g. "NYC") OR 4-letter ICAO (e.g. "KNYC").
+ * @param fromDate Inclusive start date, ISO YYYY-MM-DD (LST).
+ * @param toDate Inclusive end date, ISO YYYY-MM-DD (LST).
+ * @param opts See {@link ResearchOptions}.
+ *
+ * Returns an immutable array of frozen {@link PairsRow}s — one per LST day
+ * in `[fromDate, toDate]`. Each row carries:
+ *  - `cli_*` populated from IEM CLI (final preferred per `mergeClimate`).
+ *  - `obs_*` daily aggregates over the 3-source merged observations
+ *    (AWC > IEM > GHCNh per `mergeObservations`).
+ *  - `fcst_*` unconditionally null (Mode 1).
+ *  - `market_close_utc` formatted `YYYY-MM-DDTHH:MM:SSZ`.
+ *
+ * Throws on unknown station, malformed dates, or fromDate > toDate.
+ * AbortSignal propagates from underlying fetchers.
+ */
+declare function research(station: string, fromDate: string, toDate: string, opts?: ResearchOptions): Promise<ReadonlyArray<PairsRow>>;
+
+/** Mode 2 canonical source vocabulary. Exactly four dotted values. */
+declare const MODE2_SOURCES: readonly ["iem.archive", "iem.live", "awc.live", "ghcnh.archive"];
+/**
+ * Mode 2 source-identity type. Const-union derived from the
+ * `MODE2_SOURCES` tuple-literal (NOT a TS `enum` — `enum` defeats
+ * tree-shaking per TS Architect rubric §5).
+ */
+type Mode2Source = (typeof MODE2_SOURCES)[number];
+/**
+ * Map each canonical dotted source to the bare parser-emitted tags
+ * that satisfy it. Parsers emit bare `iem`/`awc`/`ghcnh` per
+ * packages-ts/weather; mostlyright' canonical vocab is dotted. The
+ * alias table bridges both at the boundary without rewriting the
+ * per-row source — downstream consumers see the truthful
+ * parser-emitted tag.
+ *
+ * Mirrors packages/core/src/mostlyright/mode2.py:55-63.
+ */
+declare const SOURCE_ALIASES: ReadonlyMap<Mode2Source, ReadonlySet<string>>;
+/**
+ * Type-guard: narrow an unknown value to {@link Mode2Source}. Returns
+ * true iff `value` is one of the four canonical dotted strings.
+ * Bare-form inputs (`'iem'`, `'awc'`, `'ghcnh'`) return false — TS
+ * narrows what Python widens.
+ */
+declare function isMode2Source(value: unknown): value is Mode2Source;
+/**
+ * Throw {@link SourceMismatchError} if any row's `source` field
+ * disagrees with the expected source vocabulary. Rows missing the
+ * `source` field (undefined / null / non-string) are skipped
+ * (matches Python mode2.py:181-182 — `if "source" not in df.columns:
+ * return`). Empty `rows` passes silently.
+ *
+ * The `expected` parameter accepts EITHER:
+ *
+ *  - a single string — the most common case; downstream callers
+ *    can pass `"iem.archive"` and the check is `src === "iem.archive"`.
+ *  - a `ReadonlySet<string>` — used by `researchBySource` to pass
+ *    the {@link SOURCE_ALIASES} entry so bare-form parser tags
+ *    (`'iem'`) are accepted alongside the dotted canonical form
+ *    (`'iem.archive'`). Without this, the per-row source-preserved
+ *    invariant (Python mode2.py:161-166) would force the assertion
+ *    to fire on every Mode 2 call.
+ *
+ * @param rows           rows to check (any shape with `source?: string`)
+ * @param expected       the source string OR alias-set the caller asked for
+ * @param role           role-name vocabulary; defaults to 'observations'
+ *
+ * @throws SourceMismatchError  with `schemaSource` = the expected label
+ *                              (the input string, or `[...accept].sort().join("|")`
+ *                              when an alias-set was passed), `dataSource` =
+ *                              first sorted distinct mismatched source,
+ *                              `role` = the caller-provided role,
+ *                              `catalogWarning` = null.
+ */
+declare function assertSourceIdentity<Row extends {
+    source?: string | null | undefined;
+}>(rows: ReadonlyArray<Row>, expected: string | ReadonlySet<string>, role?: SourceMismatchRole): void;
+/** Mode 2 caller-supplied options. Subset of `ResearchOptions` — Mode 2
+ *  returns observations only, so forecast + climate + cache opts are
+ *  intentionally excluded. */
+interface ResearchBySourceOptions {
+    /** Forward to the underlying fetcher; aborts the dispatch. */
+    signal?: AbortSignal;
+    /** AWC lookback window in hours (clamped by the fetcher). Default 168. */
+    awcHours?: number;
+    /** Polite-delay (ms) between IEM ASOS yearly chunks. Default 1000. */
+    iemPolitenessMs?: number;
+}
+/**
+ * Mode 2 source-explicit observation fetch.
+ *
+ * Dispatches to a single source's fetcher (no merge) and returns raw
+ * {@link Observation}s tagged with that source. Mirrors Python
+ * `mostlyright.mode2.research_by_source` (packages/core/src/mostlyright/mode2.py).
+ *
+ * The four supported sources:
+ *
+ *  - `'iem.archive'` → IEM ASOS historical CSVs (METAR + SPECI).
+ *  - `'iem.live'`    → v0.1.0 parity gap; throws. Use `'iem.archive'`.
+ *  - `'awc.live'`    → AWC live METAR JSON (≤168h lookback).
+ *  - `'ghcnh.archive'` → NCEI GHCNh PSV (US stations only).
+ *
+ * The returned rows preserve the parser-emitted per-row `source` field
+ * verbatim — NEVER rewritten to the dotted canonical form. Bare tags
+ * (`'iem'`, `'awc'`, `'ghcnh'`) survive intact so downstream Validator
+ * schemas see the truthful provenance. Mode 2 still calls
+ * {@link assertSourceIdentity} internally (defense-in-depth) before
+ * returning — using the {@link SOURCE_ALIASES} entry so the bare-form
+ * tags pass.
+ *
+ * @param station    NWS 3-letter code (e.g. `"NYC"`) OR 4-letter ICAO (e.g. `"KNYC"`).
+ * @param source     One of {@link MODE2_SOURCES}.
+ * @param fromDate   Inclusive start, ISO `YYYY-MM-DD`.
+ * @param toDate     Inclusive end, ISO `YYYY-MM-DD`.
+ * @param opts       See {@link ResearchBySourceOptions}.
+ *
+ * @returns Frozen array of {@link Observation}s whose `source` is in
+ *          `SOURCE_ALIASES.get(source)`. Empty array on no data
+ *          (NOT a throw).
+ *
+ * @throws Error              if `source` is not one of {@link MODE2_SOURCES}.
+ *                            Throws BEFORE any network call — no quota burn
+ *                            on invalid input.
+ * @throws Error              if `source === 'iem.live'` (v0.1.0 parity gap;
+ *                            v0.2 will add per-month live IEM).
+ * @throws Error              if `station` is unknown, or dates are malformed.
+ * @throws NotFoundError      if `source === 'ghcnh.archive'` and `station`
+ *                            is non-US (GHCNh PSV files are US-only).
+ * @throws SourceMismatchError if a row's `source` disagrees with the alias
+ *                             set for `source` (defense-in-depth; should
+ *                             never fire under correct fetcher behavior).
+ */
+declare function researchBySource(station: string, source: Mode2Source, fromDate: string, toDate: string, opts?: ResearchBySourceOptions): Promise<ReadonlyArray<Observation>>;
+
+/** One row per station in the resolved city neighborhood. */
+interface DiscoverRow {
+    /** Echo of the input city. */
+    readonly city: string;
+    /** 4-char K-prefix ICAO. */
+    readonly station: string;
+    /**
+     * `"<issuer>:<ticker>"` markers that resolve against this station.
+     * Empty array = denylist backstop surfaced for explicit awareness.
+     */
+    readonly settlesFor: ReadonlyArray<string>;
+}
+/** Envelope mirrors the Python `df.attrs` pattern. */
+interface DiscoverResult {
+    readonly rows: ReadonlyArray<DiscoverRow>;
+    readonly city: string;
+    readonly source: "discover";
+}
+/**
+ * Return per-station discovery table for `city`.
+ *
+ * Each row shows one settlement station + the issuer:ticker markers that
+ * resolve against it. Stations in the per-city Polymarket denylist also
+ * appear with empty `settlesFor` so quants see the full neighborhood
+ * before deciding whether to use `stationOverride`.
+ *
+ * @example
+ *   const result = discover({ city: "NYC" });
+ *   // rows include {station: "KNYC", settlesFor: ["kalshi:NYC"]},
+ *   //              {station: "KLGA", settlesFor: ["polymarket:nyc"]},
+ *   //              {station: "KJFK", settlesFor: []},  // denylist
+ *   //              {station: "KEWR", settlesFor: []}.
+ */
+declare function discover(args: {
+    readonly city: string;
+}): DiscoverResult;
+
+declare const version = "0.0.0";
+
+export { type DiscoverResult, type DiscoverRow, MODE2_SOURCES, type Mode2Source, type ResearchBySourceOptions, type ResearchOptions, SELECTOR_NAMES, SOURCE_ALIASES, type SelectorArgs, type SelectorName, type StationOverrideWarning, annotateSettlesFor, assertSourceIdentity, buildOverrideWarning, discover, isMode2Source, research, researchBySource, resolveCity, resolveContract, validateSelectors, version };