@mostlyrightmd/core 1.1.3 → 1.4.0

package/dist/preprocessing/index.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Physics-based clipping defaults for canonical observation columns.
+ *
+ * Mirrors Python `mostlyright.preprocessing.PHYSICS_BOUNDS` (preprocessing.py:34-46).
+ * Values are `[min, max]` tuples in canonical units (°C for temp, m/s and kt
+ * for wind, hPa for pressure, percent for humidity, mm for precip).
+ *
+ * Both `dew_point_c`/`dewpoint_c` and `wind_dir_deg`/`wind_dir_degrees` are
+ * aliased to support legacy + canonical column names.
+ */
+declare const PHYSICS_BOUNDS: ReadonlyMap<string, readonly [number, number]>;
+interface ClipOutliersOptions {
+    /** Explicit `[lo, hi]` range. Overrides PHYSICS_BOUNDS and sigma fallback. */
+    bounds?: readonly [number, number];
+    /** Sigma multiplier for the fallback branch. Default 3.0. Must be > 0. */
+    std?: number;
+}
+/**
+ * Winsorize a numeric column.
+ *
+ * Mirrors Python `mostlyright.preprocessing.clip_outliers`. Returns rows with
+ * a derived `{col}_clipped` column; the source `col` is preserved unchanged.
+ *
+ * Decision tree:
+ *  - `opts.bounds` set            → clip to explicit `[lo, hi]`
+ *  - `PHYSICS_BOUNDS.has(col)`    → clip to physics defaults
+ *  - else                         → sigma fallback (`mu ± std*sigma`)
+ *
+ * **Phase 3.5 review-iter fixes:**
+ *  - Throws `RangeError` if `std ≤ 0` in the sigma fallback (matches Python
+ *    `ValueError` at preprocessing.py:84-88; silent dataset corruption
+ *    otherwise).
+ *  - Sigma=0 pass-through: when all values are identical, sample sigma is
+ *    zero and the clamp `[mu, mu]` would collapse the column. Pass values
+ *    through unchanged instead.
+ *
+ * @param rows  input rows (NOT mutated; pure function)
+ * @param col   column to clip
+ * @param opts  optional bounds / std overrides; defaults: PHYSICS_BOUNDS or sigma=3
+ * @returns     new array of rows, each carrying `{col}_clipped`
+ * @throws RangeError  if sigma fallback would use `std <= 0` or non-finite std
+ */
+declare function clipOutliers<Row extends Record<string, unknown>>(rows: ReadonlyArray<Row>, col: string, opts?: ClipOutliersOptions): ReadonlyArray<Row & Record<string, number | null>>;
+
+/** Options for {@link crosscheckIemGhcnh}. */
+interface CrosscheckOptions {
+    /**
+     * Maximum acceptable absolute delta in °C between paired IEM/GHCNh
+     * `temp_c` values. Defaults to `2.0` °C (matches Python
+     * `crosscheck_iem_ghcnh(tol_c=2.0)`). A delta strictly greater than
+     * `tolC` produces a disagreement row; equality does NOT.
+     */
+    tolC?: number;
+}
+/**
+ * Disagreement row emitted by {@link crosscheckIemGhcnh}. Keys are
+ * camelCase per the TS-idiom Parity-Ticket; Python's snake_case
+ * equivalents are `event_time`, `temp_c_iem`, `temp_c_ghcnh`, `delta_c`.
+ */
+interface CrosscheckDisagreement {
+    readonly station: string;
+    readonly eventTime: string;
+    readonly tempCIem: number;
+    readonly tempCGhcnh: number;
+    readonly deltaC: number;
+}
+/**
+ * Minimal row shape consumed by {@link crosscheckIemGhcnh}. Rows MUST
+ * carry `station: string`, `eventTime: string`, and `temp_c: number |
+ * null` (or `undefined`/non-finite, which are skipped). Additional keys
+ * are allowed and ignored.
+ */
+interface CrosscheckRowIn {
+    station?: unknown;
+    eventTime?: unknown;
+    temp_c?: unknown;
+}
+/**
+ * Cross-check IEM and GHCNh temperatures; return rows where the two
+ * sources disagree above `opts.tolC` (default 2.0 °C).
+ *
+ * Algorithm:
+ * 1. If `iemRows.length === 0 || ghcnhRows.length === 0` → return `[]`
+ *    (matches Python qc.py:212-215).
+ * 2. Validate `station` + `eventTime` present (string) on every input
+ *    row; throw `Error` on first violation (parity with Python
+ *    `ValueError` at qc.py:217-220).
+ * 3. Build `iemMap: Map<string, IemRow>` keyed by
+ *    `${row.station}|${row.eventTime}`. On duplicate keys, LAST iem row
+ *    wins — deterministic but a documented deviation from Python's
+ *    `pd.merge` (which would cartesian-product duplicates).
+ * 4. For each GHCNh row, look up the matching IEM row by composite key.
+ *    If missing → skip. If either `temp_c` is null / non-finite →
+ *    skip.
+ * 5. If `Math.abs(iem.temp_c - ghcnh.temp_c) > tolC` → emit a
+ *    disagreement row. STRICT `>` (NOT `>=`).
+ *
+ * Output array order matches the iteration order of `ghcnhRows`
+ * (deterministic, independent of `iemRows` order).
+ *
+ * Pure: input arrays are NOT mutated.
+ *
+ * @param iemRows  IEM observation rows.
+ * @param ghcnhRows  GHCNh observation rows.
+ * @param opts  Tolerance options. `tolC` default = 2.0.
+ * @throws Error if any iem or ghcnh row is missing `station` or
+ *   `eventTime` (or they are not strings).
+ */
+declare function crosscheckIemGhcnh(iemRows: ReadonlyArray<CrosscheckRowIn>, ghcnhRows: ReadonlyArray<CrosscheckRowIn>, opts?: CrosscheckOptions): ReadonlyArray<CrosscheckDisagreement>;
+
+export { type ClipOutliersOptions, type CrosscheckDisagreement, type CrosscheckOptions, PHYSICS_BOUNDS, clipOutliers, crosscheckIemGhcnh as iemCrosscheck };

package/dist/preprocessing/index.mjs

@@ -0,0 +1,121 @@
+// src/transforms/clip.ts
+var PHYSICS_BOUNDS = /* @__PURE__ */ new Map([
+  ["temp_c", [-89, 57]],
+  ["dew_point_c", [-89, 35]],
+  ["dewpoint_c", [-89, 35]],
+  ["wind_speed_ms", [0, 100]],
+  ["wind_speed_kt", [0, 200]],
+  ["wind_dir_deg", [0, 360]],
+  ["wind_dir_degrees", [0, 360]],
+  ["slp_hpa", [870, 1085]],
+  ["sea_level_pressure_mb", [870, 1085]],
+  ["relative_humidity_pct_2m", [0, 100]],
+  ["precip_mm_1h", [0, 305]]
+]);
+function clipOutliers(rows, col, opts = {}) {
+  const std = opts.std ?? 3;
+  const key = `${col}_clipped`;
+  let lo;
+  let hi;
+  let passThrough = false;
+  if (opts.bounds !== void 0) {
+    [lo, hi] = opts.bounds;
+  } else if (PHYSICS_BOUNDS.has(col)) {
+    const b = PHYSICS_BOUNDS.get(col);
+    if (b === void 0) {
+      throw new Error(`PHYSICS_BOUNDS.get(${col}) unexpectedly undefined`);
+    }
+    [lo, hi] = b;
+  } else {
+    if (!Number.isFinite(std) || std <= 0) {
+      throw new RangeError(
+        `clipOutliers: std must be > 0 for the sigma fallback (got ${std}); pass bounds=[lo, hi] or use a physics-default column`
+      );
+    }
+    const vals = [];
+    for (const r of rows) {
+      const v = r?.[col];
+      if (typeof v === "number" && Number.isFinite(v)) vals.push(v);
+    }
+    if (vals.length < 2) {
+      passThrough = true;
+      lo = Number.NEGATIVE_INFINITY;
+      hi = Number.POSITIVE_INFINITY;
+    } else {
+      const mu = vals.reduce((a, b) => a + b, 0) / vals.length;
+      const sumSq = vals.reduce((a, b) => a + (b - mu) ** 2, 0);
+      const sigma = Math.sqrt(sumSq / (vals.length - 1));
+      if (sigma === 0 || !Number.isFinite(sigma)) {
+        passThrough = true;
+        lo = Number.NEGATIVE_INFINITY;
+        hi = Number.POSITIVE_INFINITY;
+      } else {
+        lo = mu - std * sigma;
+        hi = mu + std * sigma;
+      }
+    }
+  }
+  const out = [];
+  for (const r of rows) {
+    const v = r?.[col];
+    let clipped;
+    if (typeof v === "number" && Number.isFinite(v)) {
+      clipped = passThrough ? v : Math.min(Math.max(v, lo), hi);
+    } else {
+      clipped = null;
+    }
+    out.push({ ...r, [key]: clipped });
+  }
+  return out;
+}
+
+// src/qc/crosscheck.ts
+function crosscheckIemGhcnh(iemRows, ghcnhRows, opts = {}) {
+  const tolC = opts.tolC ?? 2;
+  if (iemRows.length === 0 || ghcnhRows.length === 0) return [];
+  for (const r of iemRows) {
+    if (typeof r?.station !== "string" || typeof r?.eventTime !== "string") {
+      throw new Error(
+        "crosscheckIemGhcnh: iem rows must carry 'station' (string) and 'eventTime' (string) keys"
+      );
+    }
+  }
+  for (const r of ghcnhRows) {
+    if (typeof r?.station !== "string" || typeof r?.eventTime !== "string") {
+      throw new Error(
+        "crosscheckIemGhcnh: ghcnh rows must carry 'station' (string) and 'eventTime' (string) keys"
+      );
+    }
+  }
+  const iemMap = /* @__PURE__ */ new Map();
+  for (const r of iemRows) {
+    const key = `${r.station}|${r.eventTime}`;
+    iemMap.set(key, r);
+  }
+  const out = [];
+  for (const g of ghcnhRows) {
+    const key = `${g.station}|${g.eventTime}`;
+    const i = iemMap.get(key);
+    if (i === void 0) continue;
+    const iT = typeof i.temp_c === "number" && Number.isFinite(i.temp_c) ? i.temp_c : null;
+    const gT = typeof g.temp_c === "number" && Number.isFinite(g.temp_c) ? g.temp_c : null;
+    if (iT === null || gT === null) continue;
+    const delta = Math.abs(iT - gT);
+    if (delta > tolC) {
+      out.push({
+        station: g.station,
+        eventTime: g.eventTime,
+        tempCIem: iT,
+        tempCGhcnh: gT,
+        deltaC: delta
+      });
+    }
+  }
+  return out;
+}
+export {
+  PHYSICS_BOUNDS,
+  clipOutliers,
+  crosscheckIemGhcnh as iemCrosscheck
+};
+//# sourceMappingURL=index.mjs.map

package/dist/preprocessing/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/transforms/clip.ts","../../src/qc/crosscheck.ts"],"sourcesContent":["// TS-W4 Plan 04 Task 2 — clipOutliers (winsorize) + PHYSICS_BOUNDS.\n//\n// Pure row→row port of Python `mostlyright.preprocessing.clip_outliers` at\n// packages/core/src/mostlyright/preprocessing.py:49-91. The v0.1.0 canonical\n// surface (supersedes the older `transforms.clip_outliers`).\n//\n// Decision tree (mirrors Python preprocessing.py:75-91):\n//   1. opts.bounds set            → clip to explicit [lo, hi]\n//   2. PHYSICS_BOUNDS.has(col)    → clip to physics defaults\n//   3. else                       → sigma fallback (mu ± std*sigma)\n//\n// Phase 3.5 review-iter HIGH fixes (preserved here):\n//   - Architect iter-1 HIGH: std<=0 in the sigma branch silently collapses\n//     every row to the mean. Python raises ValueError; we throw RangeError.\n//   - Sigma=0 pass-through: when all values are identical, sample sigma is\n//     zero and the clamp [mu, mu] would collapse the column. Pass values\n//     through unchanged instead (a TS-side improvement on top of Python).\n//\n// Numeric coercion is STRICT: only `typeof v === 'number' && Number.isFinite(v)`\n// passes through. Strings like '5' do NOT auto-parse. Matches Wave 2/3/04-task1.\n\n/**\n * Physics-based clipping defaults for canonical observation columns.\n *\n * Mirrors Python `mostlyright.preprocessing.PHYSICS_BOUNDS` (preprocessing.py:34-46).\n * Values are `[min, max]` tuples in canonical units (°C for temp, m/s and kt\n * for wind, hPa for pressure, percent for humidity, mm for precip).\n *\n * Both `dew_point_c`/`dewpoint_c` and `wind_dir_deg`/`wind_dir_degrees` are\n * aliased to support legacy + canonical column names.\n */\nexport const PHYSICS_BOUNDS: ReadonlyMap<string, readonly [number, number]> = new Map([\n  [\"temp_c\", [-89.0, 57.0] as const],\n  [\"dew_point_c\", [-89.0, 35.0] as const],\n  [\"dewpoint_c\", [-89.0, 35.0] as const],\n  [\"wind_speed_ms\", [0.0, 100.0] as const],\n  [\"wind_speed_kt\", [0.0, 200.0] as const],\n  [\"wind_dir_deg\", [0.0, 360.0] as const],\n  [\"wind_dir_degrees\", [0.0, 360.0] as const],\n  [\"slp_hpa\", [870.0, 1085.0] as const],\n  [\"sea_level_pressure_mb\", [870.0, 1085.0] as const],\n  [\"relative_humidity_pct_2m\", [0.0, 100.0] as const],\n  [\"precip_mm_1h\", [0.0, 305.0] as const],\n]);\n\nexport interface ClipOutliersOptions {\n  /** Explicit `[lo, hi]` range. Overrides PHYSICS_BOUNDS and sigma fallback. */\n  bounds?: readonly [number, number];\n  /** Sigma multiplier for the fallback branch. Default 3.0. Must be > 0. */\n  std?: number;\n}\n\n/**\n * Winsorize a numeric column.\n *\n * Mirrors Python `mostlyright.preprocessing.clip_outliers`. Returns rows with\n * a derived `{col}_clipped` column; the source `col` is preserved unchanged.\n *\n * Decision tree:\n *  - `opts.bounds` set            → clip to explicit `[lo, hi]`\n *  - `PHYSICS_BOUNDS.has(col)`    → clip to physics defaults\n *  - else                         → sigma fallback (`mu ± std*sigma`)\n *\n * **Phase 3.5 review-iter fixes:**\n *  - Throws `RangeError` if `std ≤ 0` in the sigma fallback (matches Python\n *    `ValueError` at preprocessing.py:84-88; silent dataset corruption\n *    otherwise).\n *  - Sigma=0 pass-through: when all values are identical, sample sigma is\n *    zero and the clamp `[mu, mu]` would collapse the column. Pass values\n *    through unchanged instead.\n *\n * @param rows  input rows (NOT mutated; pure function)\n * @param col   column to clip\n * @param opts  optional bounds / std overrides; defaults: PHYSICS_BOUNDS or sigma=3\n * @returns     new array of rows, each carrying `{col}_clipped`\n * @throws RangeError  if sigma fallback would use `std <= 0` or non-finite std\n */\nexport function clipOutliers<Row extends Record<string, unknown>>(\n  rows: ReadonlyArray<Row>,\n  col: string,\n  opts: ClipOutliersOptions = {},\n): ReadonlyArray<Row & Record<string, number | null>> {\n  const std = opts.std ?? 3.0;\n  const key = `${col}_clipped`;\n\n  // Determine clip range. `passThrough` short-circuits to \"copy value unchanged\"\n  // for the sigma=0 / n<2 edge cases (Phase 3.5 review-iter HIGH fix).\n  let lo: number;\n  let hi: number;\n  let passThrough = false;\n\n  if (opts.bounds !== undefined) {\n    [lo, hi] = opts.bounds;\n  } else if (PHYSICS_BOUNDS.has(col)) {\n    const b = PHYSICS_BOUNDS.get(col);\n    if (b === undefined) {\n      // Unreachable (we just checked has()), but the narrowing requires it.\n      throw new Error(`PHYSICS_BOUNDS.get(${col}) unexpectedly undefined`);\n    }\n    [lo, hi] = b;\n  } else {\n    // Sigma fallback. Architect iter-1 HIGH: std<=0 collapses to mu.\n    if (!Number.isFinite(std) || std <= 0) {\n      throw new RangeError(\n        `clipOutliers: std must be > 0 for the sigma fallback (got ${std}); pass bounds=[lo, hi] or use a physics-default column`,\n      );\n    }\n    // Compute mu + sigma over non-null finite values.\n    const vals: number[] = [];\n    for (const r of rows) {\n      const v = r?.[col];\n      if (typeof v === \"number\" && Number.isFinite(v)) vals.push(v);\n    }\n    if (vals.length < 2) {\n      // Not enough values to compute sample sigma → pass-through.\n      passThrough = true;\n      lo = Number.NEGATIVE_INFINITY;\n      hi = Number.POSITIVE_INFINITY;\n    } else {\n      const mu = vals.reduce((a, b) => a + b, 0) / vals.length;\n      const sumSq = vals.reduce((a, b) => a + (b - mu) ** 2, 0);\n      const sigma = Math.sqrt(sumSq / (vals.length - 1)); // sample stdev (Bessel n-1)\n      if (sigma === 0 || !Number.isFinite(sigma)) {\n        // Phase 3.5 review-iter HIGH: pass values through unchanged\n        // instead of collapsing to [mu, mu] (NOT NaN, NOT mu).\n        passThrough = true;\n        lo = Number.NEGATIVE_INFINITY;\n        hi = Number.POSITIVE_INFINITY;\n      } else {\n        lo = mu - std * sigma;\n        hi = mu + std * sigma;\n      }\n    }\n  }\n\n  const out: Array<Row & Record<string, number | null>> = [];\n  for (const r of rows) {\n    const v = r?.[col];\n    let clipped: number | null;\n    if (typeof v === \"number\" && Number.isFinite(v)) {\n      clipped = passThrough ? v : Math.min(Math.max(v, lo), hi);\n    } else {\n      clipped = null;\n    }\n    out.push({ ...(r as Row), [key]: clipped } as Row & Record<string, number | null>);\n  }\n  return out;\n}\n","// TS-W4 Plan 06 — crosscheckIemGhcnh: disagreement detection between IEM +\n// GHCNh temperature readings. Mirrors Python\n// `mostlyright.qc.crosscheck_iem_ghcnh` at\n// `packages/core/src/mostlyright/qc.py:191-228`.\n//\n// Inner-joins by composite key `(station, eventTime)`. For matched pairs\n// where both temp_c values are finite numbers and the absolute delta\n// exceeds `opts.tolC` (default 2.0 °C), emits a disagreement row.\n//\n// Threshold is STRICT `>` (NOT `>=`) per Python qc.py:228 —\n// `merged.loc[merged[\"delta_c\"] > tol_c]`. A delta exactly equal to the\n// tolerance produces NO disagreement.\n//\n// Parity-Ticket: Python returns snake_case keys\n// (event_time, temp_c_iem, temp_c_ghcnh, delta_c); TS returns camelCase\n// (eventTime, tempCIem, tempCGhcnh, deltaC) to match the TS-idiom used\n// elsewhere in the codebase (see `obsQcStatus` from Wave 5). Wire-format\n// conversion to snake_case happens at the JSON serializer boundary\n// (TS-W3 Plan 07 `jsonDumps`).\n//\n// Lives at the `@mostlyrightmd/core/qc` subpath (NOT root barrel) to keep\n// the main `@mostlyrightmd/core` bundle under its 25 KB size-limit gate.\n\n/** Options for {@link crosscheckIemGhcnh}. */\nexport interface CrosscheckOptions {\n  /**\n   * Maximum acceptable absolute delta in °C between paired IEM/GHCNh\n   * `temp_c` values. Defaults to `2.0` °C (matches Python\n   * `crosscheck_iem_ghcnh(tol_c=2.0)`). A delta strictly greater than\n   * `tolC` produces a disagreement row; equality does NOT.\n   */\n  tolC?: number;\n}\n\n/**\n * Disagreement row emitted by {@link crosscheckIemGhcnh}. Keys are\n * camelCase per the TS-idiom Parity-Ticket; Python's snake_case\n * equivalents are `event_time`, `temp_c_iem`, `temp_c_ghcnh`, `delta_c`.\n */\nexport interface CrosscheckDisagreement {\n  readonly station: string;\n  readonly eventTime: string;\n  readonly tempCIem: number;\n  readonly tempCGhcnh: number;\n  readonly deltaC: number;\n}\n\n/**\n * Minimal row shape consumed by {@link crosscheckIemGhcnh}. Rows MUST\n * carry `station: string`, `eventTime: string`, and `temp_c: number |\n * null` (or `undefined`/non-finite, which are skipped). Additional keys\n * are allowed and ignored.\n */\ninterface CrosscheckRowIn {\n  station?: unknown;\n  eventTime?: unknown;\n  temp_c?: unknown;\n}\n\n/**\n * Cross-check IEM and GHCNh temperatures; return rows where the two\n * sources disagree above `opts.tolC` (default 2.0 °C).\n *\n * Algorithm:\n * 1. If `iemRows.length === 0 || ghcnhRows.length === 0` → return `[]`\n *    (matches Python qc.py:212-215).\n * 2. Validate `station` + `eventTime` present (string) on every input\n *    row; throw `Error` on first violation (parity with Python\n *    `ValueError` at qc.py:217-220).\n * 3. Build `iemMap: Map<string, IemRow>` keyed by\n *    `${row.station}|${row.eventTime}`. On duplicate keys, LAST iem row\n *    wins — deterministic but a documented deviation from Python's\n *    `pd.merge` (which would cartesian-product duplicates).\n * 4. For each GHCNh row, look up the matching IEM row by composite key.\n *    If missing → skip. If either `temp_c` is null / non-finite →\n *    skip.\n * 5. If `Math.abs(iem.temp_c - ghcnh.temp_c) > tolC` → emit a\n *    disagreement row. STRICT `>` (NOT `>=`).\n *\n * Output array order matches the iteration order of `ghcnhRows`\n * (deterministic, independent of `iemRows` order).\n *\n * Pure: input arrays are NOT mutated.\n *\n * @param iemRows  IEM observation rows.\n * @param ghcnhRows  GHCNh observation rows.\n * @param opts  Tolerance options. `tolC` default = 2.0.\n * @throws Error if any iem or ghcnh row is missing `station` or\n *   `eventTime` (or they are not strings).\n */\nexport function crosscheckIemGhcnh(\n  iemRows: ReadonlyArray<CrosscheckRowIn>,\n  ghcnhRows: ReadonlyArray<CrosscheckRowIn>,\n  opts: CrosscheckOptions = {},\n): ReadonlyArray<CrosscheckDisagreement> {\n  const tolC = opts.tolC ?? 2.0;\n\n  if (iemRows.length === 0 || ghcnhRows.length === 0) return [];\n\n  // Validate column presence upfront (parity with Python ValueError).\n  for (const r of iemRows) {\n    if (typeof r?.station !== \"string\" || typeof r?.eventTime !== \"string\") {\n      throw new Error(\n        \"crosscheckIemGhcnh: iem rows must carry 'station' (string) and 'eventTime' (string) keys\",\n      );\n    }\n  }\n  for (const r of ghcnhRows) {\n    if (typeof r?.station !== \"string\" || typeof r?.eventTime !== \"string\") {\n      throw new Error(\n        \"crosscheckIemGhcnh: ghcnh rows must carry 'station' (string) and 'eventTime' (string) keys\",\n      );\n    }\n  }\n\n  // Build iem lookup map. Last-wins on duplicate (station, eventTime).\n  const iemMap = new Map<string, CrosscheckRowIn>();\n  for (const r of iemRows) {\n    const key = `${r.station as string}|${r.eventTime as string}`;\n    iemMap.set(key, r);\n  }\n\n  const out: CrosscheckDisagreement[] = [];\n  for (const g of ghcnhRows) {\n    const key = `${g.station as string}|${g.eventTime as string}`;\n    const i = iemMap.get(key);\n    if (i === undefined) continue;\n    const iT = typeof i.temp_c === \"number\" && Number.isFinite(i.temp_c) ? i.temp_c : null;\n    const gT = typeof g.temp_c === \"number\" && Number.isFinite(g.temp_c) ? g.temp_c : null;\n    if (iT === null || gT === null) continue;\n    const delta = Math.abs(iT - gT);\n    if (delta > tolC) {\n      out.push({\n        station: g.station as string,\n        eventTime: g.eventTime as string,\n        tempCIem: iT,\n        tempCGhcnh: gT,\n        deltaC: delta,\n      });\n    }\n  }\n  return out;\n}\n"],"mappings":"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","names":[]}

package/dist/temporal/index.cjs

@@ -23,6 +23,7 @@ __export(temporal_exports, {
   KnowledgeView: () => KnowledgeView,
   LeakageDetector: () => LeakageDetector,
   TimePoint: () => TimePoint,
+  assertIssuedAtPopulated: () => assertIssuedAtPopulated,
   assertNoLeakage: () => assertNoLeakage
 });
 module.exports = __toCommonJS(temporal_exports);
@@ -274,9 +275,9 @@ function toJsonSafe(value, seen) {
   }
   return { _repr_only: true, value: String(value) };
 }
-var TradewindsError = class extends Error {
+var MostlyRightError = class extends Error {
   /** Subclass override — the stable string enum surfaced via `errorCode`. */
-  static defaultErrorCode = "TRADEWINDS_ERROR";
+  static defaultErrorCode = "MOSTLYRIGHT_ERROR";
   errorCode;
   source;
   requestId;
@@ -308,7 +309,7 @@ var TradewindsError = class extends Error {
     return safe;
   }
 };
-var SchemaValidationError = class extends TradewindsError {
+var SchemaValidationError = class extends MostlyRightError {
   static defaultErrorCode = "SCHEMA_VALIDATION_FAILED";
   schemaId;
   violations;
@@ -331,7 +332,7 @@ var SchemaValidationError = class extends TradewindsError {
     };
   }
 };
-var LeakageError = class extends TradewindsError {
+var LeakageError = class extends MostlyRightError {
   static defaultErrorCode = "LEAKAGE_DETECTED";
   asOf;
   violatingCount;
@@ -351,6 +352,26 @@ var LeakageError = class extends TradewindsError {
     };
   }
 };
+var IssuedAtMissingError = class extends SchemaValidationError {
+  static defaultErrorCode = "ISSUED_AT_MISSING";
+  violatingCountRows;
+  constructor(message, options = {}) {
+    super(message, {
+      ...options,
+      schemaId: "schema.forecast.station.v1",
+      violations: [{ column: "issued_at", rule: "non_null" }]
+    });
+    this.violatingCountRows = options.violatingCount ?? 0;
+  }
+  payload() {
+    return {
+      ...super.payload(),
+      name: "IssuedAtMissingError",
+      violating_count: this.violatingCountRows,
+      origin_issue: "Tarabcak/mostlyright#70"
+    };
+  }
+};
 
 // src/temporal/knowledge-view.ts
 var KnowledgeView = class {
@@ -417,6 +438,7 @@ var KnowledgeView = class {
 
 // src/temporal/leakage.ts
 var SAMPLE_CAP = 10;
+var ISSUED_AT_SAMPLE_CAP = 5;
 var RUNTIME_SCHEMA_ID = "<runtime>";
 function assertNoLeakage(rows, asOf) {
   if (!(asOf instanceof TimePoint)) {
@@ -493,12 +515,42 @@ var LeakageDetector = class {
   check(rows) {
     assertNoLeakage(rows, this.#asOf);
   }
+  /**
+   * Phase 20 OM-04: defensive non-null check for `issuedAt`.
+   *
+   * Independent of `asOf` — the bound cutoff is irrelevant when the row
+   * carries no model-run time at all. Throws {@link IssuedAtMissingError}
+   * if any row's `issuedAt` is null/undefined/empty.
+   */
+  checkIssuedAt(rows) {
+    assertIssuedAtPopulated(rows);
+  }
 };
+function assertIssuedAtPopulated(rows) {
+  if (rows.length === 0) return;
+  const violations = [];
+  for (let i = 0; i < rows.length; i++) {
+    const r = rows[i];
+    const v = r == null ? null : r.issuedAt;
+    if (v == null || v === "") {
+      violations.push({ row_idx: i });
+    }
+  }
+  if (violations.length === 0) return;
+  throw new IssuedAtMissingError(
+    `${violations.length} row(s) have null issuedAt; cannot verify leakage-safety`,
+    {
+      violatingCount: violations.length,
+      sampleViolations: violations.slice(0, ISSUED_AT_SAMPLE_CAP)
+    }
+  );
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   KnowledgeView,
   LeakageDetector,
   TimePoint,
+  assertIssuedAtPopulated,
   assertNoLeakage
 });
 //# sourceMappingURL=index.cjs.map