@mostlyrightmd/core 0.1.0-rc.7

package/dist/discovery/index.d.cts

@@ -0,0 +1,313 @@
+/** Optional setters for cache writes. */
+interface CacheSetOptions {
+    /** Time-to-live in milliseconds. Implementations may honor or ignore. */
+    readonly ttlMs?: number;
+}
+/**
+ * Pluggable key/value cache contract used throughout the SDK.
+ *
+ * All methods are async — concrete implementations may resolve immediately
+ * (MemoryStore) or do I/O (FsStore / IndexedDBStore).
+ *
+ * Semantic contract:
+ *   - `get<T>(key)` returns the stored value or `null` on miss. NEVER throws
+ *     on miss.
+ *   - `set<T>(key, value, opts?)` overwrites. ttlMs is implementation-honored
+ *     (MemoryStore + IndexedDBStore honor it; FsStore ignores in v0.1).
+ *   - `delete(key)` is a no-op on miss; returns void.
+ *   - `withLock<T>(key, fn)` runs `fn` under a key-scoped exclusive lock and
+ *     releases on settle (resolve OR throw). Nested calls to the same key
+ *     serialize; calls to different keys MAY run in parallel.
+ */
+interface CacheStore {
+    get<T = unknown>(key: string): Promise<T | null>;
+    set<T = unknown>(key: string, value: T, opts?: CacheSetOptions): Promise<void>;
+    delete(key: string): Promise<void>;
+    withLock<T>(key: string, fn: () => Promise<T>): Promise<T>;
+}
+
+/**
+ * Cache-coverage summary for a station.
+ *
+ * Mirrors Python `availability()` return shape.
+ */
+interface AvailabilityResult {
+    station: string;
+    /** Count of distinct (year, month) observation cache entries. */
+    monthsCached: number;
+    /** Earliest cached month as `"YYYY-MM"`, or null if none. */
+    firstMonth: string | null;
+    /** Latest cached month as `"YYYY-MM"`, or null if none. */
+    lastMonth: string | null;
+    /** Count of cached climate years. */
+    climateYears: number;
+    /** Earliest cached climate year as `"YYYY"`, or null if none. */
+    firstClimateYear: string | null;
+    /** Latest cached climate year as `"YYYY"`, or null if none. */
+    lastClimateYear: string | null;
+}
+/**
+ * Optional adapter that lets `availability()` enumerate keys from a store.
+ *
+ * CacheStore's mandatory contract is opaque key-value: get/set/delete/withLock.
+ * Discovery needs to enumerate which keys exist for a station — this is
+ * implementation-specific (Memory iterates its Map, IndexedDB uses
+ * `getAllKeys`, Fs walks the directory tree). Stores that support enumeration
+ * implement the optional `listKeys(prefix)` method and `availability()` uses
+ * it; stores without it return zero-coverage but never throw.
+ *
+ * Listed keys may exceed the requested prefix in the result (callers filter);
+ * `listKeys` is best-effort.
+ */
+interface KeyEnumerableStore extends CacheStore {
+    listKeys(prefix: string): Promise<ReadonlyArray<string>>;
+}
+/**
+ * Options for `availability()`.
+ */
+interface AvailabilityOptions {
+    /**
+     * If true, confirm each candidate key with `cache.get()` before counting.
+     * Eliminates the small overcount possible on stores whose `listKeys()` can
+     * return keys with already-expired TTL entries (FsStore and IndexedDBStore
+     * lazy-evict on `get`, not on `listKeys` — codex iter-3 P2). Off by default
+     * because the v0.1.0 `research()` flow never writes with `ttlMs`, so the
+     * overcount window is empty; turn on only if you populate the cache with
+     * explicit TTLs.
+     *
+     * Cost: one `get()` per matching key. On warm caches this is cheap
+     * (MemoryStore + IndexedDBStore in-memory). On FsStore it reads each
+     * candidate's file.
+     */
+    readonly validate?: boolean;
+}
+/**
+ * Return a summary of cached coverage for `station`.
+ *
+ * Stores without enumeration support return a zero-coverage result with the
+ * station name populated (counts all zero, dates null).
+ *
+ * Pass `{ validate: true }` to confirm each candidate key via `cache.get()`
+ * — needed if your callers populate the cache with `ttlMs` and might query
+ * after expiry. The v0.1.0 `research()` flow does not use `ttlMs`, so the
+ * default (fast scan, no validation) is correct for the canonical path.
+ */
+declare function availability(station: string, cache: CacheStore, opts?: AvailabilityOptions): Promise<AvailabilityResult>;
+
+/** Minimal row shape consumed by `internationalDailyExtremes`. */
+interface InternationalRow {
+    /** ISO 8601 UTC instant. Must end with `Z` or include an offset. */
+    observed_at?: string | null;
+    /** Air temperature in degrees Celsius. */
+    temp_c?: number | null;
+    /** 1-hour precipitation total in millimeters. */
+    precip_mm_1h?: number | null;
+    /** Source identifier (preserved on the tmin/tmax aggregate). */
+    source?: string | null;
+}
+interface DailyExtreme {
+    /** Station-local calendar date as `YYYY-MM-DD`. */
+    localDate: string;
+    /** Count of rows with a parseable temp_c. */
+    nObs: number;
+    /** Min temperature in °C, or null on low coverage. */
+    tempMinC: number | null;
+    /** Max temperature in °C, or null on low coverage. */
+    tempMaxC: number | null;
+    /** Mean temperature in °C, or null on low coverage. */
+    tempMeanC: number | null;
+    /** Min temperature in °F, or null on low coverage. */
+    tempMinF: number | null;
+    /** Max temperature in °F, or null on low coverage. */
+    tempMaxF: number | null;
+    /** Total 1-hour precipitation across the local day, in mm. */
+    precipMm: number;
+    /** Source identifier of the row that produced tmin (or null on low coverage). */
+    sourceTmin: string | null;
+    /** Source identifier of the row that produced tmax (or null on low coverage). */
+    sourceTmax: string | null;
+}
+interface InternationalDailyExtremesOptions {
+    /** IANA timezone identifier for the station, e.g. `"Asia/Tokyo"`. Required. */
+    stationTz: string;
+    /**
+     * Decimal places for HALF_UP rounding. Defaults to 0 (whole °C) — the
+     * international convention. Pass `1` for US-station tenths.
+     */
+    precision?: number;
+    /**
+     * Minimum number of observations required for tmin/tmax/tmean to be
+     * populated. Defaults to 12 (the Python threshold). Tests can override.
+     */
+    minObs?: number;
+}
+/**
+ * Roll up observation rows to per-local-calendar-day temperature extremes.
+ *
+ * @param rows  raw observation rows (any source). Rows without a parseable
+ *              `observed_at` are dropped.
+ * @param opts  `stationTz` is required. Optional `precision` (default 0;
+ *              pass 1 for US-station tenths) and `minObs` (default 12).
+ *
+ * @returns one entry per local calendar day with at least one row. Days
+ *          with fewer than `minObs` rows have temps set to null.
+ */
+declare function internationalDailyExtremes(rows: ReadonlyArray<InternationalRow>, opts: InternationalDailyExtremesOptions): DailyExtreme[];
+
+/** Immutable reproducibility token stamping a single research() call. */
+interface DataVersion {
+    readonly sdkVersion: string;
+    readonly schemaIds: ReadonlyArray<string>;
+    readonly sources: ReadonlyArray<string>;
+    readonly codeSha: string;
+    readonly dataSha: string;
+    readonly token: string;
+}
+interface DataVersionComponents {
+    sdkVersion: string;
+    schemaIds: ReadonlyArray<string>;
+    sources: ReadonlyArray<string>;
+    codeSha: string;
+    dataSha: string;
+}
+/**
+ * Build a frozen DataVersion from explicit components.
+ *
+ * Mirrors Python `DataVersion.from_components`: sorts schemaIds + sources
+ * INTERNALLY before the canonical hash so input order does not affect the
+ * token, but preserves the caller's order on the returned object's
+ * `schemaIds` and `sources` arrays. Codex iter-5 P2: prior version sorted
+ * the stored arrays alphabetically too, which masked source-priority order
+ * (e.g. `awc.live, ghcnh, iem.archive, ...` instead of the canonical
+ * `iem.archive, iem.live, awc.live, ghcnh, nws.cli` precedence Python
+ * preserves on the tuple).
+ */
+declare function dataVersionFromComponents(components: DataVersionComponents): Promise<DataVersion>;
+/**
+ * Build a DataVersion for a research() call. Mirrors Python `DataVersion.for_research`:
+ * the codeSha encodes the call signature (`research:STATION:FROM:TO`) and dataSha
+ * is supplied by the caller (typically a cache fingerprint).
+ *
+ * The schema ids + source contract match the v0.1.0 Python SDK exactly so tokens
+ * computed in TS match tokens computed in Python for the same inputs.
+ */
+declare function dataVersionForResearch(args: {
+    sdkVersion: string;
+    station: string;
+    fromDate: string;
+    toDate: string;
+    dataSha: string;
+}): Promise<DataVersion>;
+
+/** Frozen snapshot wrapper around row data + provenance. */
+interface DataSnapshot {
+    /** ISO 8601 UTC instant when the snapshot was built (always ends with Z). */
+    readonly knowledgeTime: string;
+    /** Schema id the rows conform to. */
+    readonly schemaId: string;
+    /** Source identifier (e.g. `iem.archive`, `awc.live`). Snapshot-scoped. */
+    readonly source: string;
+    /** Row payload — opaque to this layer. Frozen. */
+    readonly rows: ReadonlyArray<Readonly<Record<string, unknown>>>;
+    /** Optional reproducibility token. */
+    readonly dataVersion: DataVersion | null;
+    /** Optional arbitrary metadata. JSON-safe-coerced on `toDict`. */
+    readonly metadata: Readonly<Record<string, unknown>>;
+    /** JSON-safe dict form. */
+    toDict(): Record<string, unknown>;
+    /** TOON-v3 tabular form (rows only — provenance lives in the dict form). */
+    toToon(): string;
+}
+interface BuildSnapshotOptions {
+    schemaId: string;
+    source: string;
+    rows: ReadonlyArray<Record<string, unknown>>;
+    knowledgeTime?: Date | string;
+    dataVersion?: DataVersion | null;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Build a frozen DataSnapshot.
+ *
+ * Throws RangeError on invalid `knowledgeTime`. Row payloads are shallow-
+ * cloned and frozen so callers can't mutate snapshot state post-build.
+ */
+declare function buildSnapshot(opts: BuildSnapshotOptions): DataSnapshot;
+
+interface TradewindsErrorOptions {
+    errorCode?: string;
+    source?: string | null;
+    requestId?: string | null;
+}
+/**
+ * Base class for all mostlyright structured errors.
+ *
+ * `errorCode` is a stable enum (e.g. "SOURCE_UNAVAILABLE") used by callers /
+ * agents to branch on without parsing message text. `source` is the source id
+ * involved (e.g. "iem.archive") when applicable, and `requestId` correlates a
+ * JSON-RPC / MCP request id when applicable.
+ */
+declare class TradewindsError extends Error {
+    /** Subclass override — the stable string enum surfaced via `errorCode`. */
+    static defaultErrorCode: string;
+    readonly errorCode: string;
+    readonly source: string | null;
+    readonly requestId: string | null;
+    constructor(message?: string, options?: TradewindsErrorOptions);
+    /**
+     * Subclass hook returning the structured attributes for `toDict`.
+     * Values are passed through `toJsonSafe` by `toDict()`, so subclasses
+     * don't need to coerce values themselves.
+     */
+    protected payload(): Record<string, unknown>;
+    /** Return a JSON-safe dict suitable for MCP `error.data`. */
+    toDict(): Record<string, unknown>;
+}
+
+interface SchemaInfo {
+    readonly id: string;
+    readonly title: string;
+    readonly columnCount: number;
+    readonly columns: ReadonlyArray<{
+        readonly name: string;
+        readonly description: string;
+        readonly nullable: boolean;
+    }>;
+}
+/**
+ * Register or override a schema for `describe()`. Built-in v0.1.0 schemas
+ * are registered at module load (BUILT_IN_SCHEMAS); callers may add custom
+ * schemas or override built-ins (e.g. with richer descriptions).
+ */
+declare function registerSchema(info: SchemaInfo): void;
+/**
+ * Return a multi-line description of a registered schema.
+ *
+ * @throws TradewindsError if `schemaId` is not registered. The error code is
+ *   `UNKNOWN_SCHEMA` so callers can distinguish from validation/IO errors.
+ */
+declare function describe(schemaId: string): string;
+/** Thrown by `describe` when `schemaId` is not registered. */
+declare class UnknownSchemaError extends TradewindsError {
+    constructor(message: string);
+    static readonly defaultErrorCode = "UNKNOWN_SCHEMA";
+}
+/**
+ * Return the transforms surface as a stable-sorted list.
+ *
+ * Matches Python `feature_catalog()`'s ordering — alphabetical on the
+ * snake_case names, here the camelCase TS names sorted identically.
+ */
+declare function featureCatalog(): ReadonlyArray<string>;
+/**
+ * Climate-gap scanning is Python-only in v0.1.0 (TS has no climate-year
+ * parquet cache yet). Throws to match the documented contract.
+ */
+declare function climateGaps(_station: string, _fromDate: string, _toDate: string): never;
+/** Thrown by `climateGaps` until the TS climate cache lands. */
+declare class ClimateGapsNotImplementedError extends TradewindsError {
+    constructor(message: string);
+    static readonly defaultErrorCode = "NOT_IMPLEMENTED";
+}
+
+export { type AvailabilityOptions, type AvailabilityResult, type BuildSnapshotOptions, ClimateGapsNotImplementedError, type DailyExtreme, type DataSnapshot, type DataVersion, type DataVersionComponents, type InternationalDailyExtremesOptions, type InternationalRow, type KeyEnumerableStore, UnknownSchemaError, availability, buildSnapshot, climateGaps, dataVersionForResearch, dataVersionFromComponents, describe, featureCatalog, internationalDailyExtremes, registerSchema };

package/dist/discovery/index.d.ts

@@ -0,0 +1,313 @@
+/** Optional setters for cache writes. */
+interface CacheSetOptions {
+    /** Time-to-live in milliseconds. Implementations may honor or ignore. */
+    readonly ttlMs?: number;
+}
+/**
+ * Pluggable key/value cache contract used throughout the SDK.
+ *
+ * All methods are async — concrete implementations may resolve immediately
+ * (MemoryStore) or do I/O (FsStore / IndexedDBStore).
+ *
+ * Semantic contract:
+ *   - `get<T>(key)` returns the stored value or `null` on miss. NEVER throws
+ *     on miss.
+ *   - `set<T>(key, value, opts?)` overwrites. ttlMs is implementation-honored
+ *     (MemoryStore + IndexedDBStore honor it; FsStore ignores in v0.1).
+ *   - `delete(key)` is a no-op on miss; returns void.
+ *   - `withLock<T>(key, fn)` runs `fn` under a key-scoped exclusive lock and
+ *     releases on settle (resolve OR throw). Nested calls to the same key
+ *     serialize; calls to different keys MAY run in parallel.
+ */
+interface CacheStore {
+    get<T = unknown>(key: string): Promise<T | null>;
+    set<T = unknown>(key: string, value: T, opts?: CacheSetOptions): Promise<void>;
+    delete(key: string): Promise<void>;
+    withLock<T>(key: string, fn: () => Promise<T>): Promise<T>;
+}
+
+/**
+ * Cache-coverage summary for a station.
+ *
+ * Mirrors Python `availability()` return shape.
+ */
+interface AvailabilityResult {
+    station: string;
+    /** Count of distinct (year, month) observation cache entries. */
+    monthsCached: number;
+    /** Earliest cached month as `"YYYY-MM"`, or null if none. */
+    firstMonth: string | null;
+    /** Latest cached month as `"YYYY-MM"`, or null if none. */
+    lastMonth: string | null;
+    /** Count of cached climate years. */
+    climateYears: number;
+    /** Earliest cached climate year as `"YYYY"`, or null if none. */
+    firstClimateYear: string | null;
+    /** Latest cached climate year as `"YYYY"`, or null if none. */
+    lastClimateYear: string | null;
+}
+/**
+ * Optional adapter that lets `availability()` enumerate keys from a store.
+ *
+ * CacheStore's mandatory contract is opaque key-value: get/set/delete/withLock.
+ * Discovery needs to enumerate which keys exist for a station — this is
+ * implementation-specific (Memory iterates its Map, IndexedDB uses
+ * `getAllKeys`, Fs walks the directory tree). Stores that support enumeration
+ * implement the optional `listKeys(prefix)` method and `availability()` uses
+ * it; stores without it return zero-coverage but never throw.
+ *
+ * Listed keys may exceed the requested prefix in the result (callers filter);
+ * `listKeys` is best-effort.
+ */
+interface KeyEnumerableStore extends CacheStore {
+    listKeys(prefix: string): Promise<ReadonlyArray<string>>;
+}
+/**
+ * Options for `availability()`.
+ */
+interface AvailabilityOptions {
+    /**
+     * If true, confirm each candidate key with `cache.get()` before counting.
+     * Eliminates the small overcount possible on stores whose `listKeys()` can
+     * return keys with already-expired TTL entries (FsStore and IndexedDBStore
+     * lazy-evict on `get`, not on `listKeys` — codex iter-3 P2). Off by default
+     * because the v0.1.0 `research()` flow never writes with `ttlMs`, so the
+     * overcount window is empty; turn on only if you populate the cache with
+     * explicit TTLs.
+     *
+     * Cost: one `get()` per matching key. On warm caches this is cheap
+     * (MemoryStore + IndexedDBStore in-memory). On FsStore it reads each
+     * candidate's file.
+     */
+    readonly validate?: boolean;
+}
+/**
+ * Return a summary of cached coverage for `station`.
+ *
+ * Stores without enumeration support return a zero-coverage result with the
+ * station name populated (counts all zero, dates null).
+ *
+ * Pass `{ validate: true }` to confirm each candidate key via `cache.get()`
+ * — needed if your callers populate the cache with `ttlMs` and might query
+ * after expiry. The v0.1.0 `research()` flow does not use `ttlMs`, so the
+ * default (fast scan, no validation) is correct for the canonical path.
+ */
+declare function availability(station: string, cache: CacheStore, opts?: AvailabilityOptions): Promise<AvailabilityResult>;
+
+/** Minimal row shape consumed by `internationalDailyExtremes`. */
+interface InternationalRow {
+    /** ISO 8601 UTC instant. Must end with `Z` or include an offset. */
+    observed_at?: string | null;
+    /** Air temperature in degrees Celsius. */
+    temp_c?: number | null;
+    /** 1-hour precipitation total in millimeters. */
+    precip_mm_1h?: number | null;
+    /** Source identifier (preserved on the tmin/tmax aggregate). */
+    source?: string | null;
+}
+interface DailyExtreme {
+    /** Station-local calendar date as `YYYY-MM-DD`. */
+    localDate: string;
+    /** Count of rows with a parseable temp_c. */
+    nObs: number;
+    /** Min temperature in °C, or null on low coverage. */
+    tempMinC: number | null;
+    /** Max temperature in °C, or null on low coverage. */
+    tempMaxC: number | null;
+    /** Mean temperature in °C, or null on low coverage. */
+    tempMeanC: number | null;
+    /** Min temperature in °F, or null on low coverage. */
+    tempMinF: number | null;
+    /** Max temperature in °F, or null on low coverage. */
+    tempMaxF: number | null;
+    /** Total 1-hour precipitation across the local day, in mm. */
+    precipMm: number;
+    /** Source identifier of the row that produced tmin (or null on low coverage). */
+    sourceTmin: string | null;
+    /** Source identifier of the row that produced tmax (or null on low coverage). */
+    sourceTmax: string | null;
+}
+interface InternationalDailyExtremesOptions {
+    /** IANA timezone identifier for the station, e.g. `"Asia/Tokyo"`. Required. */
+    stationTz: string;
+    /**
+     * Decimal places for HALF_UP rounding. Defaults to 0 (whole °C) — the
+     * international convention. Pass `1` for US-station tenths.
+     */
+    precision?: number;
+    /**
+     * Minimum number of observations required for tmin/tmax/tmean to be
+     * populated. Defaults to 12 (the Python threshold). Tests can override.
+     */
+    minObs?: number;
+}
+/**
+ * Roll up observation rows to per-local-calendar-day temperature extremes.
+ *
+ * @param rows  raw observation rows (any source). Rows without a parseable
+ *              `observed_at` are dropped.
+ * @param opts  `stationTz` is required. Optional `precision` (default 0;
+ *              pass 1 for US-station tenths) and `minObs` (default 12).
+ *
+ * @returns one entry per local calendar day with at least one row. Days
+ *          with fewer than `minObs` rows have temps set to null.
+ */
+declare function internationalDailyExtremes(rows: ReadonlyArray<InternationalRow>, opts: InternationalDailyExtremesOptions): DailyExtreme[];
+
+/** Immutable reproducibility token stamping a single research() call. */
+interface DataVersion {
+    readonly sdkVersion: string;
+    readonly schemaIds: ReadonlyArray<string>;
+    readonly sources: ReadonlyArray<string>;
+    readonly codeSha: string;
+    readonly dataSha: string;
+    readonly token: string;
+}
+interface DataVersionComponents {
+    sdkVersion: string;
+    schemaIds: ReadonlyArray<string>;
+    sources: ReadonlyArray<string>;
+    codeSha: string;
+    dataSha: string;
+}
+/**
+ * Build a frozen DataVersion from explicit components.
+ *
+ * Mirrors Python `DataVersion.from_components`: sorts schemaIds + sources
+ * INTERNALLY before the canonical hash so input order does not affect the
+ * token, but preserves the caller's order on the returned object's
+ * `schemaIds` and `sources` arrays. Codex iter-5 P2: prior version sorted
+ * the stored arrays alphabetically too, which masked source-priority order
+ * (e.g. `awc.live, ghcnh, iem.archive, ...` instead of the canonical
+ * `iem.archive, iem.live, awc.live, ghcnh, nws.cli` precedence Python
+ * preserves on the tuple).
+ */
+declare function dataVersionFromComponents(components: DataVersionComponents): Promise<DataVersion>;
+/**
+ * Build a DataVersion for a research() call. Mirrors Python `DataVersion.for_research`:
+ * the codeSha encodes the call signature (`research:STATION:FROM:TO`) and dataSha
+ * is supplied by the caller (typically a cache fingerprint).
+ *
+ * The schema ids + source contract match the v0.1.0 Python SDK exactly so tokens
+ * computed in TS match tokens computed in Python for the same inputs.
+ */
+declare function dataVersionForResearch(args: {
+    sdkVersion: string;
+    station: string;
+    fromDate: string;
+    toDate: string;
+    dataSha: string;
+}): Promise<DataVersion>;
+
+/** Frozen snapshot wrapper around row data + provenance. */
+interface DataSnapshot {
+    /** ISO 8601 UTC instant when the snapshot was built (always ends with Z). */
+    readonly knowledgeTime: string;
+    /** Schema id the rows conform to. */
+    readonly schemaId: string;
+    /** Source identifier (e.g. `iem.archive`, `awc.live`). Snapshot-scoped. */
+    readonly source: string;
+    /** Row payload — opaque to this layer. Frozen. */
+    readonly rows: ReadonlyArray<Readonly<Record<string, unknown>>>;
+    /** Optional reproducibility token. */
+    readonly dataVersion: DataVersion | null;
+    /** Optional arbitrary metadata. JSON-safe-coerced on `toDict`. */
+    readonly metadata: Readonly<Record<string, unknown>>;
+    /** JSON-safe dict form. */
+    toDict(): Record<string, unknown>;
+    /** TOON-v3 tabular form (rows only — provenance lives in the dict form). */
+    toToon(): string;
+}
+interface BuildSnapshotOptions {
+    schemaId: string;
+    source: string;
+    rows: ReadonlyArray<Record<string, unknown>>;
+    knowledgeTime?: Date | string;
+    dataVersion?: DataVersion | null;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Build a frozen DataSnapshot.
+ *
+ * Throws RangeError on invalid `knowledgeTime`. Row payloads are shallow-
+ * cloned and frozen so callers can't mutate snapshot state post-build.
+ */
+declare function buildSnapshot(opts: BuildSnapshotOptions): DataSnapshot;
+
+interface TradewindsErrorOptions {
+    errorCode?: string;
+    source?: string | null;
+    requestId?: string | null;
+}
+/**
+ * Base class for all mostlyright structured errors.
+ *
+ * `errorCode` is a stable enum (e.g. "SOURCE_UNAVAILABLE") used by callers /
+ * agents to branch on without parsing message text. `source` is the source id
+ * involved (e.g. "iem.archive") when applicable, and `requestId` correlates a
+ * JSON-RPC / MCP request id when applicable.
+ */
+declare class TradewindsError extends Error {
+    /** Subclass override — the stable string enum surfaced via `errorCode`. */
+    static defaultErrorCode: string;
+    readonly errorCode: string;
+    readonly source: string | null;
+    readonly requestId: string | null;
+    constructor(message?: string, options?: TradewindsErrorOptions);
+    /**
+     * Subclass hook returning the structured attributes for `toDict`.
+     * Values are passed through `toJsonSafe` by `toDict()`, so subclasses
+     * don't need to coerce values themselves.
+     */
+    protected payload(): Record<string, unknown>;
+    /** Return a JSON-safe dict suitable for MCP `error.data`. */
+    toDict(): Record<string, unknown>;
+}
+
+interface SchemaInfo {
+    readonly id: string;
+    readonly title: string;
+    readonly columnCount: number;
+    readonly columns: ReadonlyArray<{
+        readonly name: string;
+        readonly description: string;
+        readonly nullable: boolean;
+    }>;
+}
+/**
+ * Register or override a schema for `describe()`. Built-in v0.1.0 schemas
+ * are registered at module load (BUILT_IN_SCHEMAS); callers may add custom
+ * schemas or override built-ins (e.g. with richer descriptions).
+ */
+declare function registerSchema(info: SchemaInfo): void;
+/**
+ * Return a multi-line description of a registered schema.
+ *
+ * @throws TradewindsError if `schemaId` is not registered. The error code is
+ *   `UNKNOWN_SCHEMA` so callers can distinguish from validation/IO errors.
+ */
+declare function describe(schemaId: string): string;
+/** Thrown by `describe` when `schemaId` is not registered. */
+declare class UnknownSchemaError extends TradewindsError {
+    constructor(message: string);
+    static readonly defaultErrorCode = "UNKNOWN_SCHEMA";
+}
+/**
+ * Return the transforms surface as a stable-sorted list.
+ *
+ * Matches Python `feature_catalog()`'s ordering — alphabetical on the
+ * snake_case names, here the camelCase TS names sorted identically.
+ */
+declare function featureCatalog(): ReadonlyArray<string>;
+/**
+ * Climate-gap scanning is Python-only in v0.1.0 (TS has no climate-year
+ * parquet cache yet). Throws to match the documented contract.
+ */
+declare function climateGaps(_station: string, _fromDate: string, _toDate: string): never;
+/** Thrown by `climateGaps` until the TS climate cache lands. */
+declare class ClimateGapsNotImplementedError extends TradewindsError {
+    constructor(message: string);
+    static readonly defaultErrorCode = "NOT_IMPLEMENTED";
+}
+
+export { type AvailabilityOptions, type AvailabilityResult, type BuildSnapshotOptions, ClimateGapsNotImplementedError, type DailyExtreme, type DataSnapshot, type DataVersion, type DataVersionComponents, type InternationalDailyExtremesOptions, type InternationalRow, type KeyEnumerableStore, UnknownSchemaError, availability, buildSnapshot, climateGaps, dataVersionForResearch, dataVersionFromComponents, describe, featureCatalog, internationalDailyExtremes, registerSchema };