@mostlyrightmd/core 1.1.2 → 1.2.0

package/dist/discovery/index.d.cts

@@ -263,6 +263,20 @@ declare class TradewindsError extends Error {
     /** Return a JSON-safe dict suitable for MCP `error.data`. */
     toDict(): Record<string, unknown>;
 }
+/** Shared reason enum — MUST match Python EXACTLY (Phase 21 D-04). */
+declare const DATA_AVAILABILITY_REASONS: readonly ["model_unavailable", "out_of_window", "cache_miss", "source_404", "source_5xx", "rate_limited"];
+type DataAvailabilityReason = (typeof DATA_AVAILABILITY_REASONS)[number];
+interface DataAvailabilityErrorOptions extends TradewindsErrorOptions {
+    reason: DataAvailabilityReason;
+    hint: string;
+}
+declare class DataAvailabilityError extends TradewindsError {
+    static defaultErrorCode: string;
+    readonly reason: DataAvailabilityReason;
+    readonly hint: string;
+    constructor(options: DataAvailabilityErrorOptions);
+    protected payload(): Record<string, unknown>;
+}
 
 interface SchemaInfo {
     readonly id: string;
@@ -299,15 +313,29 @@ declare class UnknownSchemaError extends TradewindsError {
  * 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.
+ * Climate-gap scanning — TS v1.x deferral.
+ *
+ * Phase 21 21-11 messaging upgrade: raises DataAvailabilityError with a
+ * multi-paragraph hint explaining the architectural constraint (GHCNh
+ * CSVs are 10+ MB per station-year; browser cache layer doesn't scale).
+ *
+ * @throws DataAvailabilityError with reason="model_unavailable" and a
+ *   hint pointing at the Python SDK as the supported v1.x workaround.
  */
 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";
+/**
+ * Back-compat subclass of DataAvailabilityError raised by `climateGaps`
+ * in v1.x. Existing `catch (e instanceof ClimateGapsNotImplementedError)`
+ * sites keep working; new code should catch the parent class
+ * `DataAvailabilityError` and dispatch on `reason === "model_unavailable"`.
+ *
+ * @deprecated Prefer catching `DataAvailabilityError` directly.
+ */
+declare class ClimateGapsNotImplementedError extends DataAvailabilityError {
+    static readonly defaultErrorCode = "DATA_AVAILABILITY";
+    constructor();
 }
 
 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

@@ -263,6 +263,20 @@ declare class TradewindsError extends Error {
     /** Return a JSON-safe dict suitable for MCP `error.data`. */
     toDict(): Record<string, unknown>;
 }
+/** Shared reason enum — MUST match Python EXACTLY (Phase 21 D-04). */
+declare const DATA_AVAILABILITY_REASONS: readonly ["model_unavailable", "out_of_window", "cache_miss", "source_404", "source_5xx", "rate_limited"];
+type DataAvailabilityReason = (typeof DATA_AVAILABILITY_REASONS)[number];
+interface DataAvailabilityErrorOptions extends TradewindsErrorOptions {
+    reason: DataAvailabilityReason;
+    hint: string;
+}
+declare class DataAvailabilityError extends TradewindsError {
+    static defaultErrorCode: string;
+    readonly reason: DataAvailabilityReason;
+    readonly hint: string;
+    constructor(options: DataAvailabilityErrorOptions);
+    protected payload(): Record<string, unknown>;
+}
 
 interface SchemaInfo {
     readonly id: string;
@@ -299,15 +313,29 @@ declare class UnknownSchemaError extends TradewindsError {
  * 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.
+ * Climate-gap scanning — TS v1.x deferral.
+ *
+ * Phase 21 21-11 messaging upgrade: raises DataAvailabilityError with a
+ * multi-paragraph hint explaining the architectural constraint (GHCNh
+ * CSVs are 10+ MB per station-year; browser cache layer doesn't scale).
+ *
+ * @throws DataAvailabilityError with reason="model_unavailable" and a
+ *   hint pointing at the Python SDK as the supported v1.x workaround.
  */
 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";
+/**
+ * Back-compat subclass of DataAvailabilityError raised by `climateGaps`
+ * in v1.x. Existing `catch (e instanceof ClimateGapsNotImplementedError)`
+ * sites keep working; new code should catch the parent class
+ * `DataAvailabilityError` and dispatch on `reason === "model_unavailable"`.
+ *
+ * @deprecated Prefer catching `DataAvailabilityError` directly.
+ */
+declare class ClimateGapsNotImplementedError extends DataAvailabilityError {
+    static readonly defaultErrorCode = "DATA_AVAILABILITY";
+    constructor();
 }
 
 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.mjs

@@ -1064,6 +1064,40 @@ var TradewindsError = class extends Error {
     return safe;
   }
 };
+var DATA_AVAILABILITY_REASONS = [
+  "model_unavailable",
+  "out_of_window",
+  "cache_miss",
+  "source_404",
+  "source_5xx",
+  "rate_limited"
+];
+var DataAvailabilityError = class extends TradewindsError {
+  static defaultErrorCode = "DATA_AVAILABILITY";
+  reason;
+  hint;
+  constructor(options) {
+    if (!DATA_AVAILABILITY_REASONS.includes(options.reason)) {
+      throw new RangeError(
+        `DataAvailabilityError: unknown reason "${String(options.reason)}". Valid reasons: ${DATA_AVAILABILITY_REASONS.join(", ")}`
+      );
+    }
+    if (typeof options.hint !== "string" || options.hint.length === 0) {
+      throw new TypeError("DataAvailabilityError: hint is required and must be a non-empty string");
+    }
+    const message = `[${options.reason}] ${options.hint}`;
+    super(message, options);
+    this.reason = options.reason;
+    this.hint = options.hint;
+  }
+  payload() {
+    return {
+      ...super.payload(),
+      reason: this.reason,
+      hint: this.hint
+    };
+  }
+};
 
 // src/formats/toon.ts
 var SAFE_KEY_RE = /^[A-Za-z_][A-Za-z0-9_.]*$/;
@@ -1581,17 +1615,20 @@ var FEATURE_NAMES = Object.freeze([
 function featureCatalog() {
   return FEATURE_NAMES;
 }
+var CLIMATE_GAPS_HINT = "climateGaps() is server-only in v1.x. Architectural reason: GHCNh CSVs are 10+ MB per station-year; browser fetch doesn't slice (no HTTP Range) and IndexedDB quotas don't fit the working set. Use the Python SDK (mostlyright.discover.climate_gaps) for v1.x, or wait for the hosted climate-gap-precompute API (target: post-v1.x). See https://mostlyright.md/docs/sdk/typescript/climate-gaps for details.";
 function climateGaps(_station, _fromDate, _toDate) {
-  throw new ClimateGapsNotImplementedError(
-    "climateGaps is Python-only in v0.1.0; the TS climate cache lands in v0.2"
-  );
+  throw new ClimateGapsNotImplementedError();
 }
-var ClimateGapsNotImplementedError = class extends TradewindsError {
-  constructor(message) {
-    super(message);
+var ClimateGapsNotImplementedError = class extends DataAvailabilityError {
+  static defaultErrorCode = "DATA_AVAILABILITY";
+  constructor() {
+    super({
+      reason: "model_unavailable",
+      source: "climate-cache-browser",
+      hint: CLIMATE_GAPS_HINT
+    });
     this.name = "ClimateGapsNotImplementedError";
   }
-  static defaultErrorCode = "NOT_IMPLEMENTED";
 };
 export {
   ClimateGapsNotImplementedError,