@mostlyrightmd/core 0.1.0-rc.7

package/dist/internal/fs-O6XR4WWW.mjs

@@ -0,0 +1,183 @@
+// src/internal/cache/fs.ts
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import * as properLockfile from "proper-lockfile";
+var _legacyCacheDirWarned = false;
+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 join(homedir(), ".mostlyright", "cache-ts");
+}
+function _resetLegacyCacheDirWarn() {
+  _legacyCacheDirWarned = false;
+}
+var 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 join(this.#root, `${safe}.json`);
+  }
+  async get(key) {
+    const p = this.#pathFor(key);
+    let raw;
+    try {
+      raw = await 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 rm(p, { force: true });
+      } catch {
+      }
+      return null;
+    }
+    return entry.value;
+  }
+  async set(key, value, opts) {
+    const p = this.#pathFor(key);
+    await mkdir(dirname(p), { recursive: true });
+    const entry = opts?.ttlMs !== void 0 ? { value, expiresAt: Date.now() + opts.ttlMs } : { value };
+    const tmp = `${p}.${randomUUID()}.tmp`;
+    try {
+      await writeFile(tmp, JSON.stringify(entry), "utf8");
+      await rename(tmp, p);
+    } catch (e) {
+      try {
+        await rm(tmp, { force: true });
+      } catch {
+      }
+      throw e;
+    }
+  }
+  async delete(key) {
+    const p = this.#pathFor(key);
+    try {
+      await 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 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 mkdir(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;
+  }
+};
+export {
+  FsStore,
+  _resetLegacyCacheDirWarn,
+  defaultFsRoot
+};
+//# sourceMappingURL=fs-O6XR4WWW.mjs.map

package/dist/internal/fs-O6XR4WWW.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/internal/cache/fs.ts"],"sourcesContent":["// FsStore — node:fs/promises + proper-lockfile CacheStore for Node runtimes.\n//\n// Path layout under the configured root:\n//\n//   <root>/<sanitized-key>.json\n//\n// Where `<root>` defaults to\n// `$MOSTLYRIGHT_CACHE_DIR ?? $TRADEWINDS_CACHE_DIR (legacy + warn) ??\n// $HOME/.mostlyright/cache-ts` (per TS-CACHE-02 — distinct from Python's\n// `.mostlyright/cache` so the JSON envelopes here can't shadow Python's\n// parquet files). Phase 12 W4 + review-iter2: mirrors the Python back-compat\n// shim semantics — canonical → legacy + DeprecationWarning → default.\n//\n// Atomic write: payload is written to `<path>.tmp` then renamed onto\n// `<path>` (POSIX-atomic; Windows-safe via `fs.rename`).\n//\n// withLock uses proper-lockfile against a `<path>.lock` sidecar so two\n// concurrent writers serialize per-key. The lock is taken with\n// `realpath: false` so we can lock a path whose target may not yet\n// exist.\n//\n// Divergence from Python: the Python cache is parquet + per-month station\n// files keyed by (station, year, month); TS is JSON + per-key files keyed\n// by the caller's opaque string. Station-aware key generation lives in\n// `keys.ts` (plan 03).\n\nimport { randomUUID } from \"node:crypto\";\nimport { mkdir, readFile, readdir, rename, rm, writeFile } from \"node:fs/promises\";\nimport { homedir } from \"node:os\";\nimport { dirname, join } from \"node:path\";\n\nimport * as properLockfile from \"proper-lockfile\";\n\nimport type { CacheEntry, CacheSetOptions, CacheStore } from \"./types.js\";\n\n/**\n * Resolve the cache root on each call (not cached at module load) so tests\n * can `vi.stubEnv(\"MOSTLYRIGHT_CACHE_DIR\", ...)` between cases without a\n * module reload.\n *\n * Resolution order (Phase 12 W4 + review-iter2 — mirrors Python shim):\n * 1. `MOSTLYRIGHT_CACHE_DIR` env var (canonical, post-Phase-12).\n * 2. `TRADEWINDS_CACHE_DIR` env var (legacy; emits a one-time deprecation\n *    `console.warn`; scheduled for removal in vts-0.3).\n * 3. `~/.mostlyright/cache-ts` (per TS-CACHE-02 — DISTINCT from Python's\n *    `~/.mostlyright/cache` so JSON envelopes here can't shadow Python's\n *    parquet files).\n */\nlet _legacyCacheDirWarned = false;\n\nexport function defaultFsRoot(): string {\n  const canonical = process.env.MOSTLYRIGHT_CACHE_DIR;\n  if (canonical !== undefined && canonical.length > 0) return canonical;\n  const legacy = process.env.TRADEWINDS_CACHE_DIR;\n  if (legacy !== undefined && legacy.length > 0) {\n    if (!_legacyCacheDirWarned) {\n      console.warn(\n        \"TRADEWINDS_CACHE_DIR is deprecated; use MOSTLYRIGHT_CACHE_DIR. \" +\n          \"Support will be removed in vts-0.3. \" +\n          \"Run: mv ~/.tradewinds ~/.mostlyright\",\n      );\n      _legacyCacheDirWarned = true;\n    }\n    return legacy;\n  }\n  return join(homedir(), \".mostlyright\", \"cache-ts\");\n}\n\n/** Reset the one-time TRADEWINDS_CACHE_DIR deprecation latch — TEST USE ONLY. */\nexport function _resetLegacyCacheDirWarn(): void {\n  _legacyCacheDirWarned = false;\n}\n\nexport interface FsStoreOptions {\n  /** Override root directory. Defaults to {@link defaultFsRoot}. */\n  readonly root?: string;\n}\n\n/**\n * Node-side CacheStore. Each key maps to one JSON file under the root.\n */\nexport class FsStore implements CacheStore {\n  readonly #root: string;\n  // In-process per-key promise chain. proper-lockfile guarantees\n  // cross-process exclusion but its retry-based contention resolution\n  // is order-non-deterministic — two in-process callers racing on\n  // `lock()` may acquire in either order. Layering an in-process chain\n  // ensures strict FIFO for callers within the same Node process (and\n  // serves as a cheap fast-path: only one of N in-process callers ever\n  // actually contends with proper-lockfile).\n  readonly #chain = new Map<string, Promise<unknown>>();\n\n  constructor(opts: FsStoreOptions = {}) {\n    this.#root = opts.root ?? defaultFsRoot();\n  }\n\n  /**\n   * Path resolver — `key` is sanitized via `encodeURIComponent` so that\n   *\n   *   1. `:` `/` `\\` cannot escape the root (all percent-encoded), and\n   *   2. the key → file mapping is INJECTIVE: distinct keys always map to\n   *      distinct files.\n   *\n   * Iter-13 C16 fix: the previous implementation collapsed `:` / `/` / `\\`\n   * to the literal substring `\"__\"`, which is a lossy mapping — `\"a:b\"`,\n   * `\"a/b\"`, and the literal `\"a__b\"` all hashed to `a__b.json`, so one\n   * key's write would silently overwrite (and corrupt subsequent reads of)\n   * another key. `encodeURIComponent` is bijective on string inputs and\n   * filesystem-safe on every platform we ship (POSIX + Windows): the\n   * characters it leaves unescaped (alphanumerics, `-._~!*'()`) are all\n   * legal in NTFS, APFS, and ext4 filenames, and `%` is itself legal.\n   *\n   * BREAKING in v0.1.0: on-disk cache files written by any prior\n   * pre-release of this package use the old `__`-replacement scheme and\n   * are unreadable after upgrade. This is acceptable for a local-first\n   * cache: entries are regenerated on demand from live data, and the\n   * cache directory can be safely deleted by the user.\n   */\n  #pathFor(key: string): string {\n    const safe = encodeURIComponent(key);\n    return join(this.#root, `${safe}.json`);\n  }\n\n  async get<T = unknown>(key: string): Promise<T | null> {\n    const p = this.#pathFor(key);\n    let raw: string;\n    try {\n      raw = await readFile(p, \"utf8\");\n    } catch (e: unknown) {\n      const code = (e as { code?: string }).code;\n      if (code === \"ENOENT\") return null;\n      throw e;\n    }\n    let entry: CacheEntry<T>;\n    try {\n      entry = JSON.parse(raw) as CacheEntry<T>;\n    } catch {\n      // Corrupt cache entry — treat as miss; do NOT throw. Caller\n      // re-fetches and overwrites.\n      return null;\n    }\n    if (entry.expiresAt !== undefined && Date.now() >= entry.expiresAt) {\n      // Lazy-evict: best-effort unlink, ignore failures.\n      try {\n        await rm(p, { force: true });\n      } catch {\n        // ignore\n      }\n      return null;\n    }\n    return entry.value as T;\n  }\n\n  async set<T = unknown>(key: string, value: T, opts?: CacheSetOptions): Promise<void> {\n    const p = this.#pathFor(key);\n    await mkdir(dirname(p), { recursive: true });\n    const entry: CacheEntry<T> =\n      opts?.ttlMs !== undefined ? { value, expiresAt: Date.now() + opts.ttlMs } : { value };\n    // Codex iter-2 C6: use a UNIQUE temp filename per write. Two concurrent\n    // `set(\"same-key\", ...)` calls would otherwise race on the shared\n    // `<path>.tmp`: writer A creates `<path>.tmp` and renames it to\n    // `<path>`; writer B's subsequent rename then fails with ENOENT\n    // because A's rename moved B's-in-progress temp away. With a unique\n    // per-write suffix, each writer owns its own temp file; rename-into-\n    // place stays atomic on POSIX (last-rename-wins semantics — any of\n    // the N concurrent writers' value will be the final cache contents,\n    // documented at the test that covers this).\n    const tmp = `${p}.${randomUUID()}.tmp`;\n    try {\n      await writeFile(tmp, JSON.stringify(entry), \"utf8\");\n      await rename(tmp, p);\n    } catch (e) {\n      // Best-effort cleanup if rename failed (e.g. permissions). Don't\n      // let a stale unique-temp file leak.\n      try {\n        await rm(tmp, { force: true });\n      } catch {\n        // ignore\n      }\n      throw e;\n    }\n  }\n\n  async delete(key: string): Promise<void> {\n    const p = this.#pathFor(key);\n    try {\n      await rm(p, { force: true });\n    } catch (e: unknown) {\n      const code = (e as { code?: string }).code;\n      if (code === \"ENOENT\") return;\n      throw e;\n    }\n  }\n\n  /**\n   * Enumerate keys whose stored files exist under the cache root and whose\n   * decoded form starts with `prefix`.\n   *\n   * Returns an empty list if the root directory does not exist (cold cache).\n   *\n   * TS-W6 Wave 1: used by `availability()` to count observation months and\n   * climate years for a station. The file→key mapping is the inverse of\n   * `#pathFor` (encodeURIComponent → strip `.json` → decodeURIComponent).\n   */\n  async listKeys(prefix: string): Promise<ReadonlyArray<string>> {\n    let entries: string[];\n    try {\n      entries = await readdir(this.#root);\n    } catch (e: unknown) {\n      const code = (e as { code?: string }).code;\n      if (code === \"ENOENT\") return Object.freeze([]);\n      throw e;\n    }\n    const out: string[] = [];\n    for (const name of entries) {\n      if (!name.endsWith(\".json\")) continue;\n      // Ignore the proper-lockfile lock sidecars and our own in-flight\n      // unique-temp files (`<key>.json.<uuid>.tmp`) — they end with `.tmp`\n      // not `.json`, so the suffix filter above already excludes them.\n      // The lock directories proper-lockfile creates end with `.json.lock`\n      // (a directory entry), also excluded by the `.json` suffix check.\n      const encoded = name.slice(0, -\".json\".length);\n      let decoded: string;\n      try {\n        decoded = decodeURIComponent(encoded);\n      } catch {\n        // Defensive: skip files whose names don't decode (manual placements,\n        // partial writes, etc).\n        continue;\n      }\n      if (decoded.startsWith(prefix)) {\n        out.push(decoded);\n      }\n    }\n    return Object.freeze(out);\n  }\n\n  async withLock<T>(key: string, fn: () => Promise<T>): Promise<T> {\n    const p = this.#pathFor(key);\n    // Chain in-process callers FIFO. Cross-process exclusion is layered\n    // on top via proper-lockfile inside `run()`.\n    const prev = this.#chain.get(key) ?? Promise.resolve();\n    const run = async (): Promise<T> => {\n      await mkdir(dirname(p), { recursive: true });\n      const release = await properLockfile.lock(p, {\n        realpath: false,\n        retries: { retries: 5, minTimeout: 20, maxTimeout: 200 },\n      });\n      try {\n        return await fn();\n      } finally {\n        await release();\n      }\n    };\n    const next = prev.then(run, run);\n    // Absorber tail so the chain doesn't leak unhandled rejections.\n    const absorbed = next.then(\n      () => undefined,\n      () => undefined,\n    );\n    this.#chain.set(key, absorbed);\n    absorbed.finally(() => {\n      if (this.#chain.get(key) === absorbed) this.#chain.delete(key);\n    });\n    return next;\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/internal/keys-B7C8C88N.d.cts

@@ -0,0 +1,191 @@
+/** Cache entry envelope with optional TTL. */
+interface CacheEntry<T = unknown> {
+    readonly value: T;
+    /** Epoch ms when the entry expires. Absence = no expiry. */
+    readonly expiresAt?: number;
+}
+/** 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>;
+}
+/**
+ * Canonical lock identifier for a given cache key.
+ *
+ * Pure — same key → same lock id. Used by FsStore (proper-lockfile sidecar)
+ * and IndexedDBStore (`navigator.locks.request(...)` name).
+ */
+declare function lockKeyFor(key: string): string;
+
+/**
+ * In-memory cache. Per-instance state; two MemoryStore instances do NOT
+ * share state.
+ *
+ * - Values cloned via `structuredClone` so post-`set` mutation can't leak.
+ * - ttlMs honored with lazy eviction on `get`.
+ * - withLock serializes nested calls via a per-key promise chain.
+ */
+declare class MemoryStore implements CacheStore {
+    #private;
+    get<T = unknown>(key: string): Promise<T | null>;
+    set<T = unknown>(key: string, value: T, opts?: CacheSetOptions): Promise<void>;
+    delete(key: string): Promise<void>;
+    /**
+     * 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`).
+     */
+    listKeys(prefix: string): Promise<ReadonlyArray<string>>;
+    withLock<T>(key: string, fn: () => Promise<T>): Promise<T>;
+}
+
+/** Canonical DB name. Re-exported via the cache barrel. */
+declare const DB_NAME = "mostlyright-cache-v1";
+interface IndexedDBStoreOptions {
+    /** Override the DB name. Tests pass unique values per case so they don't pollute each other. */
+    readonly dbName?: string;
+}
+/**
+ * Browser CacheStore backed by IndexedDB (via idb) + Web Locks API.
+ *
+ * When `navigator.locks` is unavailable (jsdom, edge runtimes without
+ * Web Locks), falls back to a per-key in-process promise chain.
+ */
+declare class IndexedDBStore implements CacheStore {
+    #private;
+    constructor(opts?: IndexedDBStoreOptions);
+    get<T = unknown>(key: string): Promise<T | null>;
+    set<T = unknown>(key: string, value: T, opts?: CacheSetOptions): Promise<void>;
+    delete(key: string): Promise<void>;
+    /**
+     * 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.
+     */
+    listKeys(prefix: string): Promise<ReadonlyArray<string>>;
+    withLock<T>(key: string, fn: () => Promise<T>): Promise<T>;
+}
+
+/**
+ * True iff `(year, month)` is the current LST month for `station`.
+ *
+ * Mirrors Python `_is_current_lst_month`. The current month is mutable
+ * (observations still arriving) — caching it would serve stale data.
+ */
+declare function shouldSkipCacheForCurrentLstMonth(station: string, year: number, month: number, now?: Date): boolean;
+/**
+ * True iff `year` is the current LST year for `station`. Annual analog of
+ * the monthly variant — gates the climate cache.
+ */
+declare function shouldSkipCacheForCurrentLstYear(station: string, year: number, now?: Date): boolean;
+/**
+ * True iff `(year, month)` is a **strictly past** UTC month relative to
+ * `now` — i.e. cacheable on the strictest possible temporal axis.
+ *
+ * iter-12 C14: `shouldSkipCacheForCurrentLstMonth` and `isMonthVolatile`
+ * (lives in `meta/src/research.ts`) only catch the *current* LST month
+ * and the immediate post-month volatile tail. Both predicates return
+ * false for months that lie in the FUTURE relative to `now`, or for the
+ * current UTC month when the station's LST is still in the prior UTC
+ * month (negative tz offsets near UTC midnight). An empty / partial
+ * fetch for such a month would be persisted and later served as
+ * "complete." `isWritableMonth` is a stricter additional gate: it
+ * requires the (year, month) to be lexicographically less than the
+ * UTC current month, so neither future months nor the partial current
+ * UTC month are ever cacheable — regardless of any station's LST.
+ *
+ * Mirrors Python `cache.py:_is_current_lst_month`'s implicit invariant
+ * (Python paths use parquet-on-disk which can't be written for future
+ * dates because the cache root never spawns those years). TS callers
+ * MUST gate cache reads AND writes on this predicate before applying
+ * the LST / volatile-window gates.
+ */
+declare function isWritableMonth(year: number, month: number, now: Date): boolean;
+/**
+ * True iff `year` is a **strictly past** UTC year relative to `now` —
+ * the annual analog of `isWritableMonth`.
+ *
+ * iter-12 C15: `shouldSkipCacheForCurrentLstYear` only catches the
+ * current LST year. It misses (a) future years, which would silently
+ * cache empty/incomplete data, and (b) the UTC Jan-1 boundary window
+ * where the station's LST is still in the prior calendar year (negative
+ * tz offsets) but the UTC year has already rolled over — without this
+ * gate the new UTC year, which is mutable, could be written. Stricter
+ * additional gate: require `year < now.getUTCFullYear()`. TS callers
+ * MUST gate cache reads AND writes on this predicate before applying
+ * the LST / volatile-window gates.
+ */
+declare function isWritableYear(year: number, now: Date): boolean;
+/**
+ * True iff `source` ends with `.live`.
+ *
+ * Mirrors Python `_is_live_source` byte-equivalently — accepts null /
+ * undefined / empty (returns false in all three cases).
+ */
+declare function isLiveSource(source: string | null | undefined): boolean;
+/**
+ * **TS-NEW** addition per TS-CACHE-02: archive endpoints within `days` days
+ * of `archiveAsOf` are treated as volatile (some sources amend their
+ * published data for ~30 days post-event). NOT a Python port today — file
+ * a CROSS-SDK-SYNC parity ticket if Python adopts it.
+ *
+ * Returns true iff `eventDate` falls within `[archiveAsOf - days, archiveAsOf]`
+ * (inclusive at both endpoints — an event exactly `days` days before
+ * `archiveAsOf` is still volatile and MUST be re-fetched).
+ *
+ * Events AFTER `archiveAsOf` are never volatile by this rule (deltaDays < 0).
+ */
+declare function isWithinVolatileWindow(eventDate: string, archiveAsOf: string, days?: number): boolean;
+
+/**
+ * Build the canonical observations cache key.
+ *
+ * Examples:
+ *   `cacheKeyForObservations("KNYC", 2025, 1)` →
+ *     `"mostlyright:v1:observations:KNYC:2025:01"`.
+ *   `cacheKeyForObservations("KNYC", 2025, 1, "iem")` →
+ *     `"mostlyright:v1:observations:KNYC:2025:01:iem"`.
+ *
+ * The `source` segment (optional, lowercase alphanumeric / hyphen /
+ * underscore) namespaces per-source pre-merge chunks so IEM ASOS and
+ * GHCNh writes for the same `(station, year, month)` do not collide.
+ * Omit for back-compat (sentinel preloads, fixture replays).
+ */
+declare function cacheKeyForObservations(station: string, year: number, month: number, source?: string): string;
+/**
+ * Build the canonical climate cache key (annual).
+ *
+ * Example: `cacheKeyForClimate("KNYC", 2025)` →
+ * `"mostlyright:v1:climate:KNYC:2025"`.
+ */
+declare function cacheKeyForClimate(station: string, year: number): string;
+
+export { type CacheEntry as C, DB_NAME as D, IndexedDBStore as I, MemoryStore as M, type CacheSetOptions as a, type CacheStore as b, type IndexedDBStoreOptions as c, cacheKeyForClimate as d, cacheKeyForObservations as e, isWithinVolatileWindow as f, isWritableMonth as g, isWritableYear as h, isLiveSource as i, shouldSkipCacheForCurrentLstYear as j, lockKeyFor as l, shouldSkipCacheForCurrentLstMonth as s };

package/dist/internal/keys-B7C8C88N.d.ts

@@ -0,0 +1,191 @@
+/** Cache entry envelope with optional TTL. */
+interface CacheEntry<T = unknown> {
+    readonly value: T;
+    /** Epoch ms when the entry expires. Absence = no expiry. */
+    readonly expiresAt?: number;
+}
+/** 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>;
+}
+/**
+ * Canonical lock identifier for a given cache key.
+ *
+ * Pure — same key → same lock id. Used by FsStore (proper-lockfile sidecar)
+ * and IndexedDBStore (`navigator.locks.request(...)` name).
+ */
+declare function lockKeyFor(key: string): string;
+
+/**
+ * In-memory cache. Per-instance state; two MemoryStore instances do NOT
+ * share state.
+ *
+ * - Values cloned via `structuredClone` so post-`set` mutation can't leak.
+ * - ttlMs honored with lazy eviction on `get`.
+ * - withLock serializes nested calls via a per-key promise chain.
+ */
+declare class MemoryStore implements CacheStore {
+    #private;
+    get<T = unknown>(key: string): Promise<T | null>;
+    set<T = unknown>(key: string, value: T, opts?: CacheSetOptions): Promise<void>;
+    delete(key: string): Promise<void>;
+    /**
+     * 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`).
+     */
+    listKeys(prefix: string): Promise<ReadonlyArray<string>>;
+    withLock<T>(key: string, fn: () => Promise<T>): Promise<T>;
+}
+
+/** Canonical DB name. Re-exported via the cache barrel. */
+declare const DB_NAME = "mostlyright-cache-v1";
+interface IndexedDBStoreOptions {
+    /** Override the DB name. Tests pass unique values per case so they don't pollute each other. */
+    readonly dbName?: string;
+}
+/**
+ * Browser CacheStore backed by IndexedDB (via idb) + Web Locks API.
+ *
+ * When `navigator.locks` is unavailable (jsdom, edge runtimes without
+ * Web Locks), falls back to a per-key in-process promise chain.
+ */
+declare class IndexedDBStore implements CacheStore {
+    #private;
+    constructor(opts?: IndexedDBStoreOptions);
+    get<T = unknown>(key: string): Promise<T | null>;
+    set<T = unknown>(key: string, value: T, opts?: CacheSetOptions): Promise<void>;
+    delete(key: string): Promise<void>;
+    /**
+     * 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.
+     */
+    listKeys(prefix: string): Promise<ReadonlyArray<string>>;
+    withLock<T>(key: string, fn: () => Promise<T>): Promise<T>;
+}
+
+/**
+ * True iff `(year, month)` is the current LST month for `station`.
+ *
+ * Mirrors Python `_is_current_lst_month`. The current month is mutable
+ * (observations still arriving) — caching it would serve stale data.
+ */
+declare function shouldSkipCacheForCurrentLstMonth(station: string, year: number, month: number, now?: Date): boolean;
+/**
+ * True iff `year` is the current LST year for `station`. Annual analog of
+ * the monthly variant — gates the climate cache.
+ */
+declare function shouldSkipCacheForCurrentLstYear(station: string, year: number, now?: Date): boolean;
+/**
+ * True iff `(year, month)` is a **strictly past** UTC month relative to
+ * `now` — i.e. cacheable on the strictest possible temporal axis.
+ *
+ * iter-12 C14: `shouldSkipCacheForCurrentLstMonth` and `isMonthVolatile`
+ * (lives in `meta/src/research.ts`) only catch the *current* LST month
+ * and the immediate post-month volatile tail. Both predicates return
+ * false for months that lie in the FUTURE relative to `now`, or for the
+ * current UTC month when the station's LST is still in the prior UTC
+ * month (negative tz offsets near UTC midnight). An empty / partial
+ * fetch for such a month would be persisted and later served as
+ * "complete." `isWritableMonth` is a stricter additional gate: it
+ * requires the (year, month) to be lexicographically less than the
+ * UTC current month, so neither future months nor the partial current
+ * UTC month are ever cacheable — regardless of any station's LST.
+ *
+ * Mirrors Python `cache.py:_is_current_lst_month`'s implicit invariant
+ * (Python paths use parquet-on-disk which can't be written for future
+ * dates because the cache root never spawns those years). TS callers
+ * MUST gate cache reads AND writes on this predicate before applying
+ * the LST / volatile-window gates.
+ */
+declare function isWritableMonth(year: number, month: number, now: Date): boolean;
+/**
+ * True iff `year` is a **strictly past** UTC year relative to `now` —
+ * the annual analog of `isWritableMonth`.
+ *
+ * iter-12 C15: `shouldSkipCacheForCurrentLstYear` only catches the
+ * current LST year. It misses (a) future years, which would silently
+ * cache empty/incomplete data, and (b) the UTC Jan-1 boundary window
+ * where the station's LST is still in the prior calendar year (negative
+ * tz offsets) but the UTC year has already rolled over — without this
+ * gate the new UTC year, which is mutable, could be written. Stricter
+ * additional gate: require `year < now.getUTCFullYear()`. TS callers
+ * MUST gate cache reads AND writes on this predicate before applying
+ * the LST / volatile-window gates.
+ */
+declare function isWritableYear(year: number, now: Date): boolean;
+/**
+ * True iff `source` ends with `.live`.
+ *
+ * Mirrors Python `_is_live_source` byte-equivalently — accepts null /
+ * undefined / empty (returns false in all three cases).
+ */
+declare function isLiveSource(source: string | null | undefined): boolean;
+/**
+ * **TS-NEW** addition per TS-CACHE-02: archive endpoints within `days` days
+ * of `archiveAsOf` are treated as volatile (some sources amend their
+ * published data for ~30 days post-event). NOT a Python port today — file
+ * a CROSS-SDK-SYNC parity ticket if Python adopts it.
+ *
+ * Returns true iff `eventDate` falls within `[archiveAsOf - days, archiveAsOf]`
+ * (inclusive at both endpoints — an event exactly `days` days before
+ * `archiveAsOf` is still volatile and MUST be re-fetched).
+ *
+ * Events AFTER `archiveAsOf` are never volatile by this rule (deltaDays < 0).
+ */
+declare function isWithinVolatileWindow(eventDate: string, archiveAsOf: string, days?: number): boolean;
+
+/**
+ * Build the canonical observations cache key.
+ *
+ * Examples:
+ *   `cacheKeyForObservations("KNYC", 2025, 1)` →
+ *     `"mostlyright:v1:observations:KNYC:2025:01"`.
+ *   `cacheKeyForObservations("KNYC", 2025, 1, "iem")` →
+ *     `"mostlyright:v1:observations:KNYC:2025:01:iem"`.
+ *
+ * The `source` segment (optional, lowercase alphanumeric / hyphen /
+ * underscore) namespaces per-source pre-merge chunks so IEM ASOS and
+ * GHCNh writes for the same `(station, year, month)` do not collide.
+ * Omit for back-compat (sentinel preloads, fixture replays).
+ */
+declare function cacheKeyForObservations(station: string, year: number, month: number, source?: string): string;
+/**
+ * Build the canonical climate cache key (annual).
+ *
+ * Example: `cacheKeyForClimate("KNYC", 2025)` →
+ * `"mostlyright:v1:climate:KNYC:2025"`.
+ */
+declare function cacheKeyForClimate(station: string, year: number): string;
+
+export { type CacheEntry as C, DB_NAME as D, IndexedDBStore as I, MemoryStore as M, type CacheSetOptions as a, type CacheStore as b, type IndexedDBStoreOptions as c, cacheKeyForClimate as d, cacheKeyForObservations as e, isWithinVolatileWindow as f, isWritableMonth as g, isWritableYear as h, isLiveSource as i, shouldSkipCacheForCurrentLstYear as j, lockKeyFor as l, shouldSkipCacheForCurrentLstMonth as s };

package/dist/internal/merge/index.cjs

@@ -0,0 +1,75 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/internal/merge/index.ts
+var merge_exports = {};
+__export(merge_exports, {
+  SOURCE_PRIORITY: () => SOURCE_PRIORITY,
+  mergeClimate: () => mergeClimate,
+  mergeObservations: () => mergeObservations
+});
+module.exports = __toCommonJS(merge_exports);
+
+// src/internal/merge/observations.ts
+var SOURCE_PRIORITY = Object.freeze({
+  awc: 3,
+  iem: 2,
+  ghcnh: 1
+});
+function mergeObservations(rows) {
+  const best = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const key = `${row.station_code}\0${row.observed_at}\0${row.observation_type}`;
+    const existing = best.get(key);
+    if (existing === void 0) {
+      best.set(key, row);
+      continue;
+    }
+    const priority = SOURCE_PRIORITY[row.source] ?? 0;
+    const existingPriority = SOURCE_PRIORITY[existing.source] ?? 0;
+    if (priority > existingPriority) {
+      best.set(key, row);
+    }
+  }
+  return Array.from(best.values());
+}
+
+// src/internal/merge/climate.ts
+function mergeClimate(rows) {
+  const best = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const key = `${row.station_code}\0${row.observation_date}`;
+    const existing = best.get(key);
+    if (existing === void 0) {
+      best.set(key, row);
+      continue;
+    }
+    if (row.report_type_priority > existing.report_type_priority) {
+      best.set(key, row);
+    }
+  }
+  return Array.from(best.values());
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SOURCE_PRIORITY,
+  mergeClimate,
+  mergeObservations
+});
+//# sourceMappingURL=index.cjs.map