@mostlyrightmd/core 0.1.0-rc.7

package/dist/internal/cache/index.cjs

@@ -0,0 +1,1389 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/internal/cache/fs.ts
+var fs_exports = {};
+__export(fs_exports, {
+  FsStore: () => FsStore,
+  _resetLegacyCacheDirWarn: () => _resetLegacyCacheDirWarn,
+  defaultFsRoot: () => defaultFsRoot
+});
+function defaultFsRoot() {
+  const canonical = process.env.MOSTLYRIGHT_CACHE_DIR;
+  if (canonical !== void 0 && canonical.length > 0) return canonical;
+  const legacy = process.env.TRADEWINDS_CACHE_DIR;
+  if (legacy !== void 0 && legacy.length > 0) {
+    if (!_legacyCacheDirWarned) {
+      console.warn(
+        "TRADEWINDS_CACHE_DIR is deprecated; use MOSTLYRIGHT_CACHE_DIR. Support will be removed in vts-0.3. Run: mv ~/.tradewinds ~/.mostlyright"
+      );
+      _legacyCacheDirWarned = true;
+    }
+    return legacy;
+  }
+  return (0, import_node_path.join)((0, import_node_os.homedir)(), ".mostlyright", "cache-ts");
+}
+function _resetLegacyCacheDirWarn() {
+  _legacyCacheDirWarned = false;
+}
+var import_node_crypto, import_promises, import_node_os, import_node_path, properLockfile, _legacyCacheDirWarned, FsStore;
+var init_fs = __esm({
+  "src/internal/cache/fs.ts"() {
+    "use strict";
+    import_node_crypto = require("crypto");
+    import_promises = require("fs/promises");
+    import_node_os = require("os");
+    import_node_path = require("path");
+    properLockfile = __toESM(require("proper-lockfile"), 1);
+    _legacyCacheDirWarned = false;
+    FsStore = class {
+      #root;
+      // In-process per-key promise chain. proper-lockfile guarantees
+      // cross-process exclusion but its retry-based contention resolution
+      // is order-non-deterministic — two in-process callers racing on
+      // `lock()` may acquire in either order. Layering an in-process chain
+      // ensures strict FIFO for callers within the same Node process (and
+      // serves as a cheap fast-path: only one of N in-process callers ever
+      // actually contends with proper-lockfile).
+      #chain = /* @__PURE__ */ new Map();
+      constructor(opts = {}) {
+        this.#root = opts.root ?? defaultFsRoot();
+      }
+      /**
+       * Path resolver — `key` is sanitized via `encodeURIComponent` so that
+       *
+       *   1. `:` `/` `\` cannot escape the root (all percent-encoded), and
+       *   2. the key → file mapping is INJECTIVE: distinct keys always map to
+       *      distinct files.
+       *
+       * Iter-13 C16 fix: the previous implementation collapsed `:` / `/` / `\`
+       * to the literal substring `"__"`, which is a lossy mapping — `"a:b"`,
+       * `"a/b"`, and the literal `"a__b"` all hashed to `a__b.json`, so one
+       * key's write would silently overwrite (and corrupt subsequent reads of)
+       * another key. `encodeURIComponent` is bijective on string inputs and
+       * filesystem-safe on every platform we ship (POSIX + Windows): the
+       * characters it leaves unescaped (alphanumerics, `-._~!*'()`) are all
+       * legal in NTFS, APFS, and ext4 filenames, and `%` is itself legal.
+       *
+       * BREAKING in v0.1.0: on-disk cache files written by any prior
+       * pre-release of this package use the old `__`-replacement scheme and
+       * are unreadable after upgrade. This is acceptable for a local-first
+       * cache: entries are regenerated on demand from live data, and the
+       * cache directory can be safely deleted by the user.
+       */
+      #pathFor(key) {
+        const safe = encodeURIComponent(key);
+        return (0, import_node_path.join)(this.#root, `${safe}.json`);
+      }
+      async get(key) {
+        const p = this.#pathFor(key);
+        let raw;
+        try {
+          raw = await (0, import_promises.readFile)(p, "utf8");
+        } catch (e) {
+          const code = e.code;
+          if (code === "ENOENT") return null;
+          throw e;
+        }
+        let entry;
+        try {
+          entry = JSON.parse(raw);
+        } catch {
+          return null;
+        }
+        if (entry.expiresAt !== void 0 && Date.now() >= entry.expiresAt) {
+          try {
+            await (0, import_promises.rm)(p, { force: true });
+          } catch {
+          }
+          return null;
+        }
+        return entry.value;
+      }
+      async set(key, value, opts) {
+        const p = this.#pathFor(key);
+        await (0, import_promises.mkdir)((0, import_node_path.dirname)(p), { recursive: true });
+        const entry = opts?.ttlMs !== void 0 ? { value, expiresAt: Date.now() + opts.ttlMs } : { value };
+        const tmp = `${p}.${(0, import_node_crypto.randomUUID)()}.tmp`;
+        try {
+          await (0, import_promises.writeFile)(tmp, JSON.stringify(entry), "utf8");
+          await (0, import_promises.rename)(tmp, p);
+        } catch (e) {
+          try {
+            await (0, import_promises.rm)(tmp, { force: true });
+          } catch {
+          }
+          throw e;
+        }
+      }
+      async delete(key) {
+        const p = this.#pathFor(key);
+        try {
+          await (0, import_promises.rm)(p, { force: true });
+        } catch (e) {
+          const code = e.code;
+          if (code === "ENOENT") return;
+          throw e;
+        }
+      }
+      /**
+       * Enumerate keys whose stored files exist under the cache root and whose
+       * decoded form starts with `prefix`.
+       *
+       * Returns an empty list if the root directory does not exist (cold cache).
+       *
+       * TS-W6 Wave 1: used by `availability()` to count observation months and
+       * climate years for a station. The file→key mapping is the inverse of
+       * `#pathFor` (encodeURIComponent → strip `.json` → decodeURIComponent).
+       */
+      async listKeys(prefix) {
+        let entries;
+        try {
+          entries = await (0, import_promises.readdir)(this.#root);
+        } catch (e) {
+          const code = e.code;
+          if (code === "ENOENT") return Object.freeze([]);
+          throw e;
+        }
+        const out = [];
+        for (const name of entries) {
+          if (!name.endsWith(".json")) continue;
+          const encoded = name.slice(0, -".json".length);
+          let decoded;
+          try {
+            decoded = decodeURIComponent(encoded);
+          } catch {
+            continue;
+          }
+          if (decoded.startsWith(prefix)) {
+            out.push(decoded);
+          }
+        }
+        return Object.freeze(out);
+      }
+      async withLock(key, fn) {
+        const p = this.#pathFor(key);
+        const prev = this.#chain.get(key) ?? Promise.resolve();
+        const run = async () => {
+          await (0, import_promises.mkdir)((0, import_node_path.dirname)(p), { recursive: true });
+          const release = await properLockfile.lock(p, {
+            realpath: false,
+            retries: { retries: 5, minTimeout: 20, maxTimeout: 200 }
+          });
+          try {
+            return await fn();
+          } finally {
+            await release();
+          }
+        };
+        const next = prev.then(run, run);
+        const absorbed = next.then(
+          () => void 0,
+          () => void 0
+        );
+        this.#chain.set(key, absorbed);
+        absorbed.finally(() => {
+          if (this.#chain.get(key) === absorbed) this.#chain.delete(key);
+        });
+        return next;
+      }
+    };
+  }
+});
+
+// src/internal/cache/index.ts
+var cache_exports = {};
+__export(cache_exports, {
+  INDEXEDDB_DB_NAME: () => DB_NAME,
+  IndexedDBStore: () => IndexedDBStore,
+  MemoryStore: () => MemoryStore,
+  cacheKeyForClimate: () => cacheKeyForClimate,
+  cacheKeyForObservations: () => cacheKeyForObservations,
+  defaultCacheStore: () => defaultCacheStore,
+  isLiveSource: () => isLiveSource,
+  isWithinVolatileWindow: () => isWithinVolatileWindow,
+  isWritableMonth: () => isWritableMonth,
+  isWritableYear: () => isWritableYear,
+  lockKeyFor: () => lockKeyFor,
+  shouldSkipCacheForCurrentLstMonth: () => shouldSkipCacheForCurrentLstMonth,
+  shouldSkipCacheForCurrentLstYear: () => shouldSkipCacheForCurrentLstYear
+});
+module.exports = __toCommonJS(cache_exports);
+
+// src/internal/cache/types.ts
+function lockKeyFor(key) {
+  return `mostlyright:cache:lock:${key}`;
+}
+
+// src/internal/cache/memory.ts
+var MemoryStore = class {
+  #entries = /* @__PURE__ */ new Map();
+  #chain = /* @__PURE__ */ new Map();
+  async get(key) {
+    const e = this.#entries.get(key);
+    if (e === void 0) return null;
+    if (e.expiresAt !== void 0 && Date.now() >= e.expiresAt) {
+      this.#entries.delete(key);
+      return null;
+    }
+    return structuredClone(e.value);
+  }
+  async set(key, value, opts) {
+    const cloned = structuredClone(value);
+    const entry = opts?.ttlMs !== void 0 ? { value: cloned, expiresAt: Date.now() + opts.ttlMs } : { value: cloned };
+    this.#entries.set(key, entry);
+  }
+  async delete(key) {
+    this.#entries.delete(key);
+  }
+  /**
+   * Enumerate live (non-expired) keys with the given prefix.
+   *
+   * TS-W6 Wave 1: `availability()` uses this to count cached observation
+   * months and climate years per station. Expired entries are evicted as a
+   * side effect (same lazy-eviction policy as `.get`).
+   */
+  async listKeys(prefix) {
+    const now = Date.now();
+    const out = [];
+    for (const [key, entry] of this.#entries) {
+      if (entry.expiresAt !== void 0 && now >= entry.expiresAt) {
+        this.#entries.delete(key);
+        continue;
+      }
+      if (key.startsWith(prefix)) {
+        out.push(key);
+      }
+    }
+    return Object.freeze(out);
+  }
+  async withLock(key, fn) {
+    const prev = this.#chain.get(key) ?? Promise.resolve();
+    const next = prev.then(
+      () => fn(),
+      () => fn()
+    );
+    const absorbed = next.then(
+      () => void 0,
+      () => void 0
+    );
+    this.#chain.set(key, absorbed);
+    absorbed.finally(() => {
+      if (this.#chain.get(key) === absorbed) {
+        this.#chain.delete(key);
+      }
+    });
+    return next;
+  }
+};
+
+// src/internal/cache/indexeddb.ts
+var import_idb = require("idb");
+var DB_NAME = "mostlyright-cache-v1";
+var STORE_NAME = "entries";
+var SCHEMA_VERSION = 1;
+function getWebLocks() {
+  if (typeof navigator === "undefined") return null;
+  const nav = navigator;
+  return nav.locks ?? null;
+}
+var IndexedDBStore = class {
+  #dbName;
+  #dbPromise;
+  #chain = /* @__PURE__ */ new Map();
+  constructor(opts = {}) {
+    this.#dbName = opts.dbName ?? DB_NAME;
+    this.#dbPromise = (0, import_idb.openDB)(this.#dbName, SCHEMA_VERSION, {
+      upgrade(db) {
+        if (!db.objectStoreNames.contains(STORE_NAME)) {
+          db.createObjectStore(STORE_NAME);
+        }
+      }
+    });
+  }
+  async get(key) {
+    const db = await this.#dbPromise;
+    const entry = await db.get(STORE_NAME, key);
+    if (entry === void 0) return null;
+    if (entry.expiresAt !== void 0 && Date.now() >= entry.expiresAt) {
+      try {
+        await db.delete(STORE_NAME, key);
+      } catch {
+      }
+      return null;
+    }
+    return entry.value;
+  }
+  async set(key, value, opts) {
+    const db = await this.#dbPromise;
+    const entry = opts?.ttlMs !== void 0 ? { value, expiresAt: Date.now() + opts.ttlMs } : { value };
+    await db.put(STORE_NAME, entry, key);
+  }
+  async delete(key) {
+    const db = await this.#dbPromise;
+    await db.delete(STORE_NAME, key);
+  }
+  /**
+   * Enumerate keys with the given prefix using IndexedDB's bounded range
+   * query. Live keys only — expired entries are lazy-evicted on read by
+   * `get()`, so a stale-but-not-yet-evicted entry can appear here; callers
+   * who care about expiration should `get()` to confirm.
+   *
+   * TS-W6 Wave 1: `availability()` uses this to count observation months and
+   * climate years for a station.
+   */
+  async listKeys(prefix) {
+    const db = await this.#dbPromise;
+    const range = IDBKeyRange.bound(prefix, `${prefix}\uFFFF`, false, false);
+    const keys = await db.getAllKeys(STORE_NAME, range);
+    const out = [];
+    for (const k of keys) {
+      if (typeof k === "string" && k.startsWith(prefix)) {
+        out.push(k);
+      }
+    }
+    return Object.freeze(out);
+  }
+  async withLock(key, fn) {
+    const locks = getWebLocks();
+    if (locks !== null) {
+      return locks.request(lockKeyFor(key), { mode: "exclusive" }, () => fn());
+    }
+    const prev = this.#chain.get(key) ?? Promise.resolve();
+    const next = prev.then(
+      () => fn(),
+      () => fn()
+    );
+    const absorbed = next.then(
+      () => void 0,
+      () => void 0
+    );
+    this.#chain.set(key, absorbed);
+    absorbed.finally(() => {
+      if (this.#chain.get(key) === absorbed) this.#chain.delete(key);
+    });
+    return next;
+  }
+};
+
+// src/internal/cache/default.ts
+async function defaultCacheStore() {
+  if (typeof indexedDB !== "undefined") return new IndexedDBStore();
+  if (typeof process !== "undefined" && typeof process.versions === "object" && process.versions !== null && typeof process.versions.node === "string") {
+    const { FsStore: FsStore2 } = await Promise.resolve().then(() => (init_fs(), fs_exports));
+    return new FsStore2();
+  }
+  return new MemoryStore();
+}
+
+// src/data/generated/stations.ts
+var STATIONS = [
+  {
+    code: "EDDB",
+    country: "DE",
+    ghcnh_id: null,
+    icao: "EDDB",
+    latitude: 52.3667,
+    longitude: 13.5033,
+    name: "Berlin Brandenburg",
+    tz: "Europe/Berlin"
+  },
+  {
+    code: "EDDF",
+    country: "DE",
+    ghcnh_id: null,
+    icao: "EDDF",
+    latitude: 50.0379,
+    longitude: 8.5622,
+    name: "Frankfurt am Main",
+    tz: "Europe/Berlin"
+  },
+  {
+    code: "EDDM",
+    country: "DE",
+    ghcnh_id: null,
+    icao: "EDDM",
+    latitude: 48.3538,
+    longitude: 11.7861,
+    name: "Munich Franz Josef Strauss",
+    tz: "Europe/Berlin"
+  },
+  {
+    code: "EFHK",
+    country: "FI",
+    ghcnh_id: null,
+    icao: "EFHK",
+    latitude: 60.3172,
+    longitude: 24.9633,
+    name: "Helsinki-Vantaa",
+    tz: "Europe/Helsinki"
+  },
+  {
+    code: "EGKK",
+    country: "GB",
+    ghcnh_id: null,
+    icao: "EGKK",
+    latitude: 51.1481,
+    longitude: -0.1903,
+    name: "London Gatwick",
+    tz: "Europe/London"
+  },
+  {
+    code: "EGLL",
+    country: "GB",
+    ghcnh_id: null,
+    icao: "EGLL",
+    latitude: 51.4706,
+    longitude: -0.4619,
+    name: "London Heathrow",
+    tz: "Europe/London"
+  },
+  {
+    code: "EHAM",
+    country: "NL",
+    ghcnh_id: null,
+    icao: "EHAM",
+    latitude: 52.3086,
+    longitude: 4.7639,
+    name: "Amsterdam Schiphol",
+    tz: "Europe/Amsterdam"
+  },
+  {
+    code: "EKCH",
+    country: "DK",
+    ghcnh_id: null,
+    icao: "EKCH",
+    latitude: 55.6181,
+    longitude: 12.6561,
+    name: "Copenhagen Kastrup",
+    tz: "Europe/Copenhagen"
+  },
+  {
+    code: "EPWA",
+    country: "PL",
+    ghcnh_id: null,
+    icao: "EPWA",
+    latitude: 52.1657,
+    longitude: 20.9671,
+    name: "Warsaw Chopin",
+    tz: "Europe/Warsaw"
+  },
+  {
+    code: "ESSA",
+    country: "SE",
+    ghcnh_id: null,
+    icao: "ESSA",
+    latitude: 59.6519,
+    longitude: 17.9186,
+    name: "Stockholm Arlanda",
+    tz: "Europe/Stockholm"
+  },
+  {
+    code: "ATL",
+    country: "US",
+    ghcnh_id: "USW00013874",
+    icao: "KATL",
+    latitude: 33.6407,
+    longitude: -84.4277,
+    name: "Hartsfield-Jackson Atlanta International",
+    tz: "America/New_York"
+  },
+  {
+    code: "AUS",
+    country: "US",
+    ghcnh_id: "USW00013904",
+    icao: "KAUS",
+    latitude: 30.1975,
+    longitude: -97.6664,
+    name: "Austin-Bergstrom International",
+    tz: "America/Chicago"
+  },
+  {
+    code: "BOS",
+    country: "US",
+    ghcnh_id: "USW00014739",
+    icao: "KBOS",
+    latitude: 42.3656,
+    longitude: -71.0096,
+    name: "Boston Logan International",
+    tz: "America/New_York"
+  },
+  {
+    code: "DCA",
+    country: "US",
+    ghcnh_id: "USW00013743",
+    icao: "KDCA",
+    latitude: 38.8512,
+    longitude: -77.0402,
+    name: "Washington Reagan National",
+    tz: "America/New_York"
+  },
+  {
+    code: "DEN",
+    country: "US",
+    ghcnh_id: "USW00003017",
+    icao: "KDEN",
+    latitude: 39.8561,
+    longitude: -104.6737,
+    name: "Denver International",
+    tz: "America/Denver"
+  },
+  {
+    code: "DFW",
+    country: "US",
+    ghcnh_id: "USW00003927",
+    icao: "KDFW",
+    latitude: 32.8998,
+    longitude: -97.0403,
+    name: "Dallas-Fort Worth International",
+    tz: "America/Chicago"
+  },
+  {
+    code: "HOU",
+    country: "US",
+    ghcnh_id: "USW00012918",
+    icao: "KHOU",
+    latitude: 29.6454,
+    longitude: -95.2789,
+    name: "Houston Hobby",
+    tz: "America/Chicago"
+  },
+  {
+    code: "LAS",
+    country: "US",
+    ghcnh_id: "USW00023169",
+    icao: "KLAS",
+    latitude: 36.084,
+    longitude: -115.1537,
+    name: "Harry Reid (McCarran) International",
+    tz: "America/Los_Angeles"
+  },
+  {
+    code: "LAX",
+    country: "US",
+    ghcnh_id: "USW00023174",
+    icao: "KLAX",
+    latitude: 33.9425,
+    longitude: -118.4081,
+    name: "Los Angeles International",
+    tz: "America/Los_Angeles"
+  },
+  {
+    code: "MDW",
+    country: "US",
+    ghcnh_id: "USW00014819",
+    icao: "KMDW",
+    latitude: 41.7868,
+    longitude: -87.7522,
+    name: "Chicago Midway International",
+    tz: "America/Chicago"
+  },
+  {
+    code: "MIA",
+    country: "US",
+    ghcnh_id: "USW00012839",
+    icao: "KMIA",
+    latitude: 25.7959,
+    longitude: -80.287,
+    name: "Miami International",
+    tz: "America/New_York"
+  },
+  {
+    code: "MSP",
+    country: "US",
+    ghcnh_id: "USW00014922",
+    icao: "KMSP",
+    latitude: 44.8848,
+    longitude: -93.2223,
+    name: "Minneapolis-St Paul International",
+    tz: "America/Chicago"
+  },
+  {
+    code: "MSY",
+    country: "US",
+    ghcnh_id: "USW00012916",
+    icao: "KMSY",
+    latitude: 29.9934,
+    longitude: -90.258,
+    name: "New Orleans Louis Armstrong International",
+    tz: "America/Chicago"
+  },
+  {
+    code: "NYC",
+    country: "US",
+    ghcnh_id: "USW00094728",
+    icao: "KNYC",
+    latitude: 40.7789,
+    longitude: -73.9692,
+    name: "Central Park, New York",
+    tz: "America/New_York"
+  },
+  {
+    code: "OKC",
+    country: "US",
+    ghcnh_id: "USW00013967",
+    icao: "KOKC",
+    latitude: 35.3931,
+    longitude: -97.6007,
+    name: "Oklahoma City Will Rogers World",
+    tz: "America/Chicago"
+  },
+  {
+    code: "PHL",
+    country: "US",
+    ghcnh_id: "USW00013739",
+    icao: "KPHL",
+    latitude: 39.8721,
+    longitude: -75.2411,
+    name: "Philadelphia International",
+    tz: "America/New_York"
+  },
+  {
+    code: "PHX",
+    country: "US",
+    ghcnh_id: "USW00023183",
+    icao: "KPHX",
+    latitude: 33.4373,
+    longitude: -112.0078,
+    name: "Phoenix Sky Harbor International",
+    tz: "America/Phoenix"
+  },
+  {
+    code: "SAT",
+    country: "US",
+    ghcnh_id: "USW00012921",
+    icao: "KSAT",
+    latitude: 29.5337,
+    longitude: -98.4698,
+    name: "San Antonio International",
+    tz: "America/Chicago"
+  },
+  {
+    code: "SEA",
+    country: "US",
+    ghcnh_id: "USW00024233",
+    icao: "KSEA",
+    latitude: 47.4502,
+    longitude: -122.3088,
+    name: "Seattle-Tacoma International",
+    tz: "America/Los_Angeles"
+  },
+  {
+    code: "SFO",
+    country: "US",
+    ghcnh_id: "USW00023234",
+    icao: "KSFO",
+    latitude: 37.6213,
+    longitude: -122.379,
+    name: "San Francisco International",
+    tz: "America/Los_Angeles"
+  },
+  {
+    code: "LEBL",
+    country: "ES",
+    ghcnh_id: null,
+    icao: "LEBL",
+    latitude: 41.2974,
+    longitude: 2.0833,
+    name: "Barcelona El Prat",
+    tz: "Europe/Madrid"
+  },
+  {
+    code: "LEMD",
+    country: "ES",
+    ghcnh_id: null,
+    icao: "LEMD",
+    latitude: 40.4719,
+    longitude: -3.5626,
+    name: "Madrid Barajas",
+    tz: "Europe/Madrid"
+  },
+  {
+    code: "LFPB",
+    country: "FR",
+    ghcnh_id: null,
+    icao: "LFPB",
+    latitude: 48.9694,
+    longitude: 2.4414,
+    name: "Paris Le Bourget",
+    tz: "Europe/Paris"
+  },
+  {
+    code: "LFPG",
+    country: "FR",
+    ghcnh_id: null,
+    icao: "LFPG",
+    latitude: 49.0097,
+    longitude: 2.5479,
+    name: "Paris Charles de Gaulle",
+    tz: "Europe/Paris"
+  },
+  {
+    code: "LFPO",
+    country: "FR",
+    ghcnh_id: null,
+    icao: "LFPO",
+    latitude: 48.7233,
+    longitude: 2.3794,
+    name: "Paris Orly",
+    tz: "Europe/Paris"
+  },
+  {
+    code: "LIMC",
+    country: "IT",
+    ghcnh_id: null,
+    icao: "LIMC",
+    latitude: 45.6306,
+    longitude: 8.7281,
+    name: "Milan Malpensa",
+    tz: "Europe/Rome"
+  },
+  {
+    code: "LIRF",
+    country: "IT",
+    ghcnh_id: null,
+    icao: "LIRF",
+    latitude: 41.8003,
+    longitude: 12.2389,
+    name: "Rome Fiumicino",
+    tz: "Europe/Rome"
+  },
+  {
+    code: "LOWW",
+    country: "AT",
+    ghcnh_id: null,
+    icao: "LOWW",
+    latitude: 48.1103,
+    longitude: 16.5697,
+    name: "Vienna International",
+    tz: "Europe/Vienna"
+  },
+  {
+    code: "LSZH",
+    country: "CH",
+    ghcnh_id: null,
+    icao: "LSZH",
+    latitude: 47.4647,
+    longitude: 8.5492,
+    name: "Zurich",
+    tz: "Europe/Zurich"
+  },
+  {
+    code: "NZAA",
+    country: "NZ",
+    ghcnh_id: null,
+    icao: "NZAA",
+    latitude: -37.0081,
+    longitude: 174.7917,
+    name: "Auckland",
+    tz: "Pacific/Auckland"
+  },
+  {
+    code: "NZWN",
+    country: "NZ",
+    ghcnh_id: null,
+    icao: "NZWN",
+    latitude: -41.3272,
+    longitude: 174.8053,
+    name: "Wellington",
+    tz: "Pacific/Auckland"
+  },
+  {
+    code: "OERK",
+    country: "SA",
+    ghcnh_id: null,
+    icao: "OERK",
+    latitude: 24.9576,
+    longitude: 46.6988,
+    name: "Riyadh King Khalid International",
+    tz: "Asia/Riyadh"
+  },
+  {
+    code: "OMDB",
+    country: "AE",
+    ghcnh_id: null,
+    icao: "OMDB",
+    latitude: 25.2532,
+    longitude: 55.3657,
+    name: "Dubai International",
+    tz: "Asia/Dubai"
+  },
+  {
+    code: "OTHH",
+    country: "QA",
+    ghcnh_id: null,
+    icao: "OTHH",
+    latitude: 25.2731,
+    longitude: 51.608,
+    name: "Doha Hamad International",
+    tz: "Asia/Qatar"
+  },
+  {
+    code: "RCTP",
+    country: "TW",
+    ghcnh_id: null,
+    icao: "RCTP",
+    latitude: 25.0777,
+    longitude: 121.2328,
+    name: "Taipei Taoyuan",
+    tz: "Asia/Taipei"
+  },
+  {
+    code: "RJAA",
+    country: "JP",
+    ghcnh_id: null,
+    icao: "RJAA",
+    latitude: 35.7647,
+    longitude: 140.3864,
+    name: "Tokyo Narita",
+    tz: "Asia/Tokyo"
+  },
+  {
+    code: "RJTT",
+    country: "JP",
+    ghcnh_id: null,
+    icao: "RJTT",
+    latitude: 35.5522,
+    longitude: 139.78,
+    name: "Tokyo Haneda",
+    tz: "Asia/Tokyo"
+  },
+  {
+    code: "RKSI",
+    country: "KR",
+    ghcnh_id: null,
+    icao: "RKSI",
+    latitude: 37.4691,
+    longitude: 126.4505,
+    name: "Seoul Incheon",
+    tz: "Asia/Seoul"
+  },
+  {
+    code: "SAEZ",
+    country: "AR",
+    ghcnh_id: null,
+    icao: "SAEZ",
+    latitude: -34.8222,
+    longitude: -58.5358,
+    name: "Buenos Aires Ezeiza",
+    tz: "America/Argentina/Buenos_Aires"
+  },
+  {
+    code: "SBGR",
+    country: "BR",
+    ghcnh_id: null,
+    icao: "SBGR",
+    latitude: -23.4356,
+    longitude: -46.4731,
+    name: "S\xE3o Paulo Guarulhos",
+    tz: "America/Sao_Paulo"
+  },
+  {
+    code: "UUEE",
+    country: "RU",
+    ghcnh_id: null,
+    icao: "UUEE",
+    latitude: 55.9728,
+    longitude: 37.4147,
+    name: "Moscow Sheremetyevo",
+    tz: "Europe/Moscow"
+  },
+  {
+    code: "VABB",
+    country: "IN",
+    ghcnh_id: null,
+    icao: "VABB",
+    latitude: 19.0887,
+    longitude: 72.8679,
+    name: "Mumbai Chhatrapati Shivaji",
+    tz: "Asia/Kolkata"
+  },
+  {
+    code: "VHHH",
+    country: "HK",
+    ghcnh_id: null,
+    icao: "VHHH",
+    latitude: 22.308,
+    longitude: 113.9185,
+    name: "Hong Kong International",
+    tz: "Asia/Hong_Kong"
+  },
+  {
+    code: "VIDP",
+    country: "IN",
+    ghcnh_id: null,
+    icao: "VIDP",
+    latitude: 28.5562,
+    longitude: 77.1,
+    name: "Delhi Indira Gandhi",
+    tz: "Asia/Kolkata"
+  },
+  {
+    code: "VTBS",
+    country: "TH",
+    ghcnh_id: null,
+    icao: "VTBS",
+    latitude: 13.69,
+    longitude: 100.7501,
+    name: "Bangkok Suvarnabhumi",
+    tz: "Asia/Bangkok"
+  },
+  {
+    code: "WSSS",
+    country: "SG",
+    ghcnh_id: null,
+    icao: "WSSS",
+    latitude: 1.3644,
+    longitude: 103.9915,
+    name: "Singapore Changi",
+    tz: "Asia/Singapore"
+  },
+  {
+    code: "YBBN",
+    country: "AU",
+    ghcnh_id: null,
+    icao: "YBBN",
+    latitude: -27.3842,
+    longitude: 153.1175,
+    name: "Brisbane",
+    tz: "Australia/Brisbane"
+  },
+  {
+    code: "YMML",
+    country: "AU",
+    ghcnh_id: null,
+    icao: "YMML",
+    latitude: -37.6733,
+    longitude: 144.8433,
+    name: "Melbourne Tullamarine",
+    tz: "Australia/Melbourne"
+  },
+  {
+    code: "YSSY",
+    country: "AU",
+    ghcnh_id: null,
+    icao: "YSSY",
+    latitude: -33.9461,
+    longitude: 151.1772,
+    name: "Sydney Kingsford Smith",
+    tz: "Australia/Sydney"
+  },
+  {
+    code: "ZBAA",
+    country: "CN",
+    ghcnh_id: null,
+    icao: "ZBAA",
+    latitude: 40.0801,
+    longitude: 116.5846,
+    name: "Beijing Capital",
+    tz: "Asia/Shanghai"
+  },
+  {
+    code: "ZSPD",
+    country: "CN",
+    ghcnh_id: null,
+    icao: "ZSPD",
+    latitude: 31.1443,
+    longitude: 121.8083,
+    name: "Shanghai Pudong",
+    tz: "Asia/Shanghai"
+  }
+];
+var STATION_BY_CODE = /* @__PURE__ */ new Map([
+  ["ATL", STATIONS[10]],
+  ["AUS", STATIONS[11]],
+  ["BOS", STATIONS[12]],
+  ["DCA", STATIONS[13]],
+  ["DEN", STATIONS[14]],
+  ["DFW", STATIONS[15]],
+  ["EDDB", STATIONS[0]],
+  ["EDDF", STATIONS[1]],
+  ["EDDM", STATIONS[2]],
+  ["EFHK", STATIONS[3]],
+  ["EGKK", STATIONS[4]],
+  ["EGLL", STATIONS[5]],
+  ["EHAM", STATIONS[6]],
+  ["EKCH", STATIONS[7]],
+  ["EPWA", STATIONS[8]],
+  ["ESSA", STATIONS[9]],
+  ["HOU", STATIONS[16]],
+  ["LAS", STATIONS[17]],
+  ["LAX", STATIONS[18]],
+  ["LEBL", STATIONS[30]],
+  ["LEMD", STATIONS[31]],
+  ["LFPB", STATIONS[32]],
+  ["LFPG", STATIONS[33]],
+  ["LFPO", STATIONS[34]],
+  ["LIMC", STATIONS[35]],
+  ["LIRF", STATIONS[36]],
+  ["LOWW", STATIONS[37]],
+  ["LSZH", STATIONS[38]],
+  ["MDW", STATIONS[19]],
+  ["MIA", STATIONS[20]],
+  ["MSP", STATIONS[21]],
+  ["MSY", STATIONS[22]],
+  ["NYC", STATIONS[23]],
+  ["NZAA", STATIONS[39]],
+  ["NZWN", STATIONS[40]],
+  ["OERK", STATIONS[41]],
+  ["OKC", STATIONS[24]],
+  ["OMDB", STATIONS[42]],
+  ["OTHH", STATIONS[43]],
+  ["PHL", STATIONS[25]],
+  ["PHX", STATIONS[26]],
+  ["RCTP", STATIONS[44]],
+  ["RJAA", STATIONS[45]],
+  ["RJTT", STATIONS[46]],
+  ["RKSI", STATIONS[47]],
+  ["SAEZ", STATIONS[48]],
+  ["SAT", STATIONS[27]],
+  ["SBGR", STATIONS[49]],
+  ["SEA", STATIONS[28]],
+  ["SFO", STATIONS[29]],
+  ["UUEE", STATIONS[50]],
+  ["VABB", STATIONS[51]],
+  ["VHHH", STATIONS[52]],
+  ["VIDP", STATIONS[53]],
+  ["VTBS", STATIONS[54]],
+  ["WSSS", STATIONS[55]],
+  ["YBBN", STATIONS[56]],
+  ["YMML", STATIONS[57]],
+  ["YSSY", STATIONS[58]],
+  ["ZBAA", STATIONS[59]],
+  ["ZSPD", STATIONS[60]]
+]);
+var STATION_BY_ICAO = /* @__PURE__ */ new Map([
+  ["EDDB", STATIONS[0]],
+  ["EDDF", STATIONS[1]],
+  ["EDDM", STATIONS[2]],
+  ["EFHK", STATIONS[3]],
+  ["EGKK", STATIONS[4]],
+  ["EGLL", STATIONS[5]],
+  ["EHAM", STATIONS[6]],
+  ["EKCH", STATIONS[7]],
+  ["EPWA", STATIONS[8]],
+  ["ESSA", STATIONS[9]],
+  ["KATL", STATIONS[10]],
+  ["KAUS", STATIONS[11]],
+  ["KBOS", STATIONS[12]],
+  ["KDCA", STATIONS[13]],
+  ["KDEN", STATIONS[14]],
+  ["KDFW", STATIONS[15]],
+  ["KHOU", STATIONS[16]],
+  ["KLAS", STATIONS[17]],
+  ["KLAX", STATIONS[18]],
+  ["KMDW", STATIONS[19]],
+  ["KMIA", STATIONS[20]],
+  ["KMSP", STATIONS[21]],
+  ["KMSY", STATIONS[22]],
+  ["KNYC", STATIONS[23]],
+  ["KOKC", STATIONS[24]],
+  ["KPHL", STATIONS[25]],
+  ["KPHX", STATIONS[26]],
+  ["KSAT", STATIONS[27]],
+  ["KSEA", STATIONS[28]],
+  ["KSFO", STATIONS[29]],
+  ["LEBL", STATIONS[30]],
+  ["LEMD", STATIONS[31]],
+  ["LFPB", STATIONS[32]],
+  ["LFPG", STATIONS[33]],
+  ["LFPO", STATIONS[34]],
+  ["LIMC", STATIONS[35]],
+  ["LIRF", STATIONS[36]],
+  ["LOWW", STATIONS[37]],
+  ["LSZH", STATIONS[38]],
+  ["NZAA", STATIONS[39]],
+  ["NZWN", STATIONS[40]],
+  ["OERK", STATIONS[41]],
+  ["OMDB", STATIONS[42]],
+  ["OTHH", STATIONS[43]],
+  ["RCTP", STATIONS[44]],
+  ["RJAA", STATIONS[45]],
+  ["RJTT", STATIONS[46]],
+  ["RKSI", STATIONS[47]],
+  ["SAEZ", STATIONS[48]],
+  ["SBGR", STATIONS[49]],
+  ["UUEE", STATIONS[50]],
+  ["VABB", STATIONS[51]],
+  ["VHHH", STATIONS[52]],
+  ["VIDP", STATIONS[53]],
+  ["VTBS", STATIONS[54]],
+  ["WSSS", STATIONS[55]],
+  ["YBBN", STATIONS[56]],
+  ["YMML", STATIONS[57]],
+  ["YSSY", STATIONS[58]],
+  ["ZBAA", STATIONS[59]],
+  ["ZSPD", STATIONS[60]]
+]);
+
+// src/snapshot.ts
+var _STATION_TZ = Object.freeze({
+  // Eastern (UTC-5 standard / UTC-4 DST)
+  NYC: "America/New_York",
+  JFK: "America/New_York",
+  LGA: "America/New_York",
+  EWR: "America/New_York",
+  ATL: "America/New_York",
+  BOS: "America/New_York",
+  PHL: "America/New_York",
+  DCA: "America/New_York",
+  IAD: "America/New_York",
+  BWI: "America/New_York",
+  MIA: "America/New_York",
+  MCO: "America/New_York",
+  TPA: "America/New_York",
+  CLT: "America/New_York",
+  RDU: "America/New_York",
+  CLE: "America/New_York",
+  PIT: "America/New_York",
+  BUF: "America/New_York",
+  DTW: "America/Detroit",
+  IND: "America/Indiana/Indianapolis",
+  CVG: "America/New_York",
+  CMH: "America/New_York",
+  SYR: "America/New_York",
+  ALB: "America/New_York",
+  BTV: "America/New_York",
+  ORF: "America/New_York",
+  RIC: "America/New_York",
+  GSO: "America/New_York",
+  CHS: "America/New_York",
+  SAV: "America/New_York",
+  JAX: "America/New_York",
+  RSW: "America/New_York",
+  PBI: "America/New_York",
+  FLL: "America/New_York",
+  // Central (UTC-6 standard / UTC-5 DST)
+  ORD: "America/Chicago",
+  MDW: "America/Chicago",
+  DFW: "America/Chicago",
+  DAL: "America/Chicago",
+  IAH: "America/Chicago",
+  HOU: "America/Chicago",
+  MSP: "America/Chicago",
+  STL: "America/Chicago",
+  MCI: "America/Chicago",
+  OMA: "America/Chicago",
+  MKE: "America/Chicago",
+  MSY: "America/Chicago",
+  MEM: "America/Chicago",
+  BNA: "America/Chicago",
+  OKC: "America/Chicago",
+  SAT: "America/Chicago",
+  AUS: "America/Chicago",
+  DSM: "America/Chicago",
+  TUL: "America/Chicago",
+  LIT: "America/Chicago",
+  BIR: "America/Chicago",
+  SDF: "America/Chicago",
+  HSV: "America/Chicago",
+  BHM: "America/Chicago",
+  MOB: "America/Chicago",
+  BTR: "America/Chicago",
+  SHV: "America/Chicago",
+  // Mountain (UTC-7 standard / UTC-6 DST)
+  DEN: "America/Denver",
+  SLC: "America/Denver",
+  ABQ: "America/Denver",
+  BOI: "America/Boise",
+  BZN: "America/Denver",
+  GJT: "America/Denver",
+  // Arizona: no DST (UTC-7 always)
+  PHX: "America/Phoenix",
+  TUS: "America/Phoenix",
+  // Pacific (UTC-8 standard / UTC-7 DST)
+  LAX: "America/Los_Angeles",
+  SFO: "America/Los_Angeles",
+  SEA: "America/Los_Angeles",
+  PDX: "America/Los_Angeles",
+  LAS: "America/Los_Angeles",
+  SAN: "America/Los_Angeles",
+  OAK: "America/Los_Angeles",
+  SJC: "America/Los_Angeles",
+  SMF: "America/Los_Angeles",
+  RNO: "America/Los_Angeles",
+  FAT: "America/Los_Angeles",
+  SNA: "America/Los_Angeles",
+  ONT: "America/Los_Angeles",
+  BUR: "America/Los_Angeles",
+  // Alaska (UTC-9 standard / UTC-8 DST)
+  ANC: "America/Anchorage",
+  FAI: "America/Anchorage",
+  JNU: "America/Juneau",
+  // Hawaii (UTC-10, no DST)
+  HNL: "Pacific/Honolulu",
+  OGG: "Pacific/Honolulu",
+  KOA: "Pacific/Honolulu",
+  // International (iter-6 H12): minimal set required to un-skip the
+  // case-5 RJTT year-wrap cache behavior test. Python's
+  // `mostlyright.snapshot._resolve_tz` falls back to the broader STATIONS
+  // registry for intl ICAOs; the TS port hasn't ported that fallback
+  // yet (tracked as TS-W6 — exhaustive intl-station tz coverage). This
+  // entry closes H12 cleanly without pulling the whole STATIONS map in.
+  // ICAO key (RJTT) — international stations have no 3-letter NWS code.
+  // Tokyo Haneda — UTC+9 LST, no DST.
+  RJTT: "Asia/Tokyo"
+});
+var _JAN_REF = new Date(Date.UTC(2024, 0, 15, 12, 0, 0));
+var _OFFSET_CACHE = /* @__PURE__ */ new Map();
+function _lstOffsetHours(stationTz) {
+  const cached = _OFFSET_CACHE.get(stationTz);
+  if (cached !== void 0) return cached;
+  const fmt = new Intl.DateTimeFormat("en-US", {
+    timeZone: stationTz,
+    hour12: false,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit"
+  });
+  const parts = fmt.formatToParts(_JAN_REF);
+  const get = (type) => {
+    const part = parts.find((p) => p.type === type);
+    if (!part) {
+      throw new Error(`Intl.DateTimeFormat missing ${type} for tz=${stationTz}`);
+    }
+    return Number(part.value);
+  };
+  const year = get("year");
+  const month = get("month");
+  const day = get("day");
+  let hour = get("hour");
+  const minute = get("minute");
+  const second = get("second");
+  if (hour === 24) hour = 0;
+  const localAsUtc = Date.UTC(year, month - 1, day, hour, minute, second);
+  const offsetMs = localAsUtc - _JAN_REF.getTime();
+  const offsetHours = offsetMs / 36e5;
+  _OFFSET_CACHE.set(stationTz, offsetHours);
+  return offsetHours;
+}
+
+// src/internal/cache/skip-rules.ts
+function _lstOffsetHoursFor(station) {
+  const upper = station.trim().toUpperCase();
+  const byCode = STATION_BY_CODE.get(upper);
+  if (byCode !== void 0) return _lstOffsetHours(byCode.tz);
+  const byIcao = STATION_BY_ICAO.get(upper);
+  if (byIcao !== void 0) return _lstOffsetHours(byIcao.tz);
+  if (upper.length === 4 && upper.startsWith("K")) {
+    const stripped = upper.slice(1);
+    const retry = STATION_BY_CODE.get(stripped);
+    if (retry !== void 0) return _lstOffsetHours(retry.tz);
+  }
+  throw new RangeError(`unknown station: ${JSON.stringify(station)}`);
+}
+function _nowLst(station, now = /* @__PURE__ */ new Date()) {
+  const offsetHours = _lstOffsetHoursFor(station);
+  return new Date(now.getTime() + offsetHours * 36e5);
+}
+function shouldSkipCacheForCurrentLstMonth(station, year, month, now) {
+  const lst = _nowLst(station, now);
+  return lst.getUTCFullYear() === year && lst.getUTCMonth() + 1 === month;
+}
+function shouldSkipCacheForCurrentLstYear(station, year, now) {
+  const lst = _nowLst(station, now);
+  return lst.getUTCFullYear() === year;
+}
+function isWritableMonth(year, month, now) {
+  const nowYear = now.getUTCFullYear();
+  const nowMonth = now.getUTCMonth() + 1;
+  if (year < nowYear) return true;
+  if (year > nowYear) return false;
+  return month < nowMonth;
+}
+function isWritableYear(year, now) {
+  return year < now.getUTCFullYear();
+}
+function isLiveSource(source) {
+  return typeof source === "string" && source.length > 0 && source.endsWith(".live");
+}
+function isWithinVolatileWindow(eventDate, archiveAsOf, days = 30) {
+  const e = Date.parse(`${eventDate}T00:00:00Z`);
+  const a = Date.parse(`${archiveAsOf}T00:00:00Z`);
+  if (!Number.isFinite(e) || !Number.isFinite(a)) {
+    throw new RangeError(
+      `invalid YYYY-MM-DD: eventDate=${JSON.stringify(eventDate)} archiveAsOf=${JSON.stringify(archiveAsOf)}`
+    );
+  }
+  const deltaDays = (a - e) / 864e5;
+  return deltaDays >= 0 && deltaDays <= days;
+}
+
+// src/internal/cache/keys.ts
+var MIN_YEAR = 1900;
+var MAX_YEAR = 2100;
+var SOURCE_RE = /^[a-z0-9_-]+$/;
+function cacheKeyForObservations(station, year, month, source) {
+  if (!Number.isInteger(year) || year < MIN_YEAR || year > MAX_YEAR) {
+    throw new RangeError(`year out of range: ${year}`);
+  }
+  if (!Number.isInteger(month) || month < 1 || month > 12) {
+    throw new RangeError(`month out of range: ${month}`);
+  }
+  const yyyy = String(year).padStart(4, "0");
+  const mm = String(month).padStart(2, "0");
+  const base = `mostlyright:v1:observations:${station.toUpperCase()}:${yyyy}:${mm}`;
+  if (source === void 0) return base;
+  if (typeof source !== "string" || !SOURCE_RE.test(source)) {
+    throw new RangeError(
+      `source must match ${SOURCE_RE.source} (lowercase alnum / hyphen / underscore); got ${JSON.stringify(source)}`
+    );
+  }
+  return `${base}:${source}`;
+}
+function cacheKeyForClimate(station, year) {
+  if (!Number.isInteger(year) || year < MIN_YEAR || year > MAX_YEAR) {
+    throw new RangeError(`year out of range: ${year}`);
+  }
+  const yyyy = String(year).padStart(4, "0");
+  return `mostlyright:v1:climate:${station.toUpperCase()}:${yyyy}`;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  INDEXEDDB_DB_NAME,
+  IndexedDBStore,
+  MemoryStore,
+  cacheKeyForClimate,
+  cacheKeyForObservations,
+  defaultCacheStore,
+  isLiveSource,
+  isWithinVolatileWindow,
+  isWritableMonth,
+  isWritableYear,
+  lockKeyFor,
+  shouldSkipCacheForCurrentLstMonth,
+  shouldSkipCacheForCurrentLstYear
+});
+//# sourceMappingURL=index.cjs.map