@mostlyrightmd/core 0.1.0-rc.7

package/dist/internal/cache/fs.cjs

@@ -0,0 +1,217 @@
+"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 __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-entry.ts
+var fs_entry_exports = {};
+__export(fs_entry_exports, {
+  FsStore: () => FsStore,
+  defaultFsRoot: () => defaultFsRoot
+});
+module.exports = __toCommonJS(fs_entry_exports);
+
+// src/internal/cache/fs.ts
+var import_node_crypto = require("crypto");
+var import_promises = require("fs/promises");
+var import_node_os = require("os");
+var import_node_path = require("path");
+var properLockfile = __toESM(require("proper-lockfile"), 1);
+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 (0, import_node_path.join)((0, import_node_os.homedir)(), ".mostlyright", "cache-ts");
+}
+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 (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;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FsStore,
+  defaultFsRoot
+});
+//# sourceMappingURL=fs.cjs.map

package/dist/internal/cache/fs.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/internal/cache/fs-entry.ts","../../../src/internal/cache/fs.ts"],"sourcesContent":["// Node-only subpath entry for @mostlyrightmd/core/internal/cache/fs.\n//\n// Iter-2 H5: FsStore + defaultFsRoot were removed from the cache\n// barrel (`./internal/cache/index.ts`) because the re-export pulled\n// `node:fs/promises`, `node:os`, `node:path`, `node:crypto`,\n// `proper-lockfile` into the browser-facing cache subbundle (even\n// though `defaultCacheStore` uses dynamic `import('./fs.js')`).\n// This dedicated subpath exists so Node-side consumers (FsStore unit\n// tests + downstream callers who explicitly want a filesystem store)\n// can import FsStore without dragging the whole cache barrel into a\n// browser bundle.\n//\n// Package.json maps `@mostlyrightmd/core/internal/cache/fs` → this file.\n// tsup config emits it as a sibling dist entry (`dist/internal/cache/\n// fs.{mjs,cjs}`); the cache subbundle has no static import to this\n// file, so tree-shaking keeps Node imports out of MV3 bundles.\n\nexport { FsStore, defaultFsRoot } from \"./fs.js\";\nexport type { FsStoreOptions } from \"./fs.js\";\n","// 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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;AC0BA,yBAA2B;AAC3B,sBAAgE;AAChE,qBAAwB;AACxB,uBAA8B;AAE9B,qBAAgC;AAiBhC,IAAI,wBAAwB;AAErB,SAAS,gBAAwB;AACtC,QAAM,YAAY,QAAQ,IAAI;AAC9B,MAAI,cAAc,UAAa,UAAU,SAAS,EAAG,QAAO;AAC5D,QAAM,SAAS,QAAQ,IAAI;AAC3B,MAAI,WAAW,UAAa,OAAO,SAAS,GAAG;AAC7C,QAAI,CAAC,uBAAuB;AAC1B,cAAQ;AAAA,QACN;AAAA,MAGF;AACA,8BAAwB;AAAA,IAC1B;AACA,WAAO;AAAA,EACT;AACA,aAAO,2BAAK,wBAAQ,GAAG,gBAAgB,UAAU;AACnD;AAeO,IAAM,UAAN,MAAoC;AAAA,EAChC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,SAAS,oBAAI,IAA8B;AAAA,EAEpD,YAAY,OAAuB,CAAC,GAAG;AACrC,SAAK,QAAQ,KAAK,QAAQ,cAAc;AAAA,EAC1C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAwBA,SAAS,KAAqB;AAC5B,UAAM,OAAO,mBAAmB,GAAG;AACnC,eAAO,uBAAK,KAAK,OAAO,GAAG,IAAI,OAAO;AAAA,EACxC;AAAA,EAEA,MAAM,IAAiB,KAAgC;AACrD,UAAM,IAAI,KAAK,SAAS,GAAG;AAC3B,QAAI;AACJ,QAAI;AACF,YAAM,UAAM,0BAAS,GAAG,MAAM;AAAA,IAChC,SAAS,GAAY;AACnB,YAAM,OAAQ,EAAwB;AACtC,UAAI,SAAS,SAAU,QAAO;AAC9B,YAAM;AAAA,IACR;AACA,QAAI;AACJ,QAAI;AACF,cAAQ,KAAK,MAAM,GAAG;AAAA,IACxB,QAAQ;AAGN,aAAO;AAAA,IACT;AACA,QAAI,MAAM,cAAc,UAAa,KAAK,IAAI,KAAK,MAAM,WAAW;AAElE,UAAI;AACF,kBAAM,oBAAG,GAAG,EAAE,OAAO,KAAK,CAAC;AAAA,MAC7B,QAAQ;AAAA,MAER;AACA,aAAO;AAAA,IACT;AACA,WAAO,MAAM;AAAA,EACf;AAAA,EAEA,MAAM,IAAiB,KAAa,OAAU,MAAuC;AACnF,UAAM,IAAI,KAAK,SAAS,GAAG;AAC3B,cAAM,2BAAM,0BAAQ,CAAC,GAAG,EAAE,WAAW,KAAK,CAAC;AAC3C,UAAM,QACJ,MAAM,UAAU,SAAY,EAAE,OAAO,WAAW,KAAK,IAAI,IAAI,KAAK,MAAM,IAAI,EAAE,MAAM;AAUtF,UAAM,MAAM,GAAG,CAAC,QAAI,+BAAW,CAAC;AAChC,QAAI;AACF,gBAAM,2BAAU,KAAK,KAAK,UAAU,KAAK,GAAG,MAAM;AAClD,gBAAM,wBAAO,KAAK,CAAC;AAAA,IACrB,SAAS,GAAG;AAGV,UAAI;AACF,kBAAM,oBAAG,KAAK,EAAE,OAAO,KAAK,CAAC;AAAA,MAC/B,QAAQ;AAAA,MAER;AACA,YAAM;AAAA,IACR;AAAA,EACF;AAAA,EAEA,MAAM,OAAO,KAA4B;AACvC,UAAM,IAAI,KAAK,SAAS,GAAG;AAC3B,QAAI;AACF,gBAAM,oBAAG,GAAG,EAAE,OAAO,KAAK,CAAC;AAAA,IAC7B,SAAS,GAAY;AACnB,YAAM,OAAQ,EAAwB;AACtC,UAAI,SAAS,SAAU;AACvB,YAAM;AAAA,IACR;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYA,MAAM,SAAS,QAAgD;AAC7D,QAAI;AACJ,QAAI;AACF,gBAAU,UAAM,yBAAQ,KAAK,KAAK;AAAA,IACpC,SAAS,GAAY;AACnB,YAAM,OAAQ,EAAwB;AACtC,UAAI,SAAS,SAAU,QAAO,OAAO,OAAO,CAAC,CAAC;AAC9C,YAAM;AAAA,IACR;AACA,UAAM,MAAgB,CAAC;AACvB,eAAW,QAAQ,SAAS;AAC1B,UAAI,CAAC,KAAK,SAAS,OAAO,EAAG;AAM7B,YAAM,UAAU,KAAK,MAAM,GAAG,CAAC,QAAQ,MAAM;AAC7C,UAAI;AACJ,UAAI;AACF,kBAAU,mBAAmB,OAAO;AAAA,MACtC,QAAQ;AAGN;AAAA,MACF;AACA,UAAI,QAAQ,WAAW,MAAM,GAAG;AAC9B,YAAI,KAAK,OAAO;AAAA,MAClB;AAAA,IACF;AACA,WAAO,OAAO,OAAO,GAAG;AAAA,EAC1B;AAAA,EAEA,MAAM,SAAY,KAAa,IAAkC;AAC/D,UAAM,IAAI,KAAK,SAAS,GAAG;AAG3B,UAAM,OAAO,KAAK,OAAO,IAAI,GAAG,KAAK,QAAQ,QAAQ;AACrD,UAAM,MAAM,YAAwB;AAClC,gBAAM,2BAAM,0BAAQ,CAAC,GAAG,EAAE,WAAW,KAAK,CAAC;AAC3C,YAAM,UAAU,MAAqB,oBAAK,GAAG;AAAA,QAC3C,UAAU;AAAA,QACV,SAAS,EAAE,SAAS,GAAG,YAAY,IAAI,YAAY,IAAI;AAAA,MACzD,CAAC;AACD,UAAI;AACF,eAAO,MAAM,GAAG;AAAA,MAClB,UAAE;AACA,cAAM,QAAQ;AAAA,MAChB;AAAA,IACF;AACA,UAAM,OAAO,KAAK,KAAK,KAAK,GAAG;AAE/B,UAAM,WAAW,KAAK;AAAA,MACpB,MAAM;AAAA,MACN,MAAM;AAAA,IACR;AACA,SAAK,OAAO,IAAI,KAAK,QAAQ;AAC7B,aAAS,QAAQ,MAAM;AACrB,UAAI,KAAK,OAAO,IAAI,GAAG,MAAM,SAAU,MAAK,OAAO,OAAO,GAAG;AAAA,IAC/D,CAAC;AACD,WAAO;AAAA,EACT;AACF;","names":[]}

package/dist/internal/cache/fs.d.cts

@@ -0,0 +1,57 @@
+/** 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>;
+}
+
+declare function defaultFsRoot(): string;
+interface FsStoreOptions {
+    /** Override root directory. Defaults to {@link defaultFsRoot}. */
+    readonly root?: string;
+}
+/**
+ * Node-side CacheStore. Each key maps to one JSON file under the root.
+ */
+declare class FsStore implements CacheStore {
+    #private;
+    constructor(opts?: FsStoreOptions);
+    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 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).
+     */
+    listKeys(prefix: string): Promise<ReadonlyArray<string>>;
+    withLock<T>(key: string, fn: () => Promise<T>): Promise<T>;
+}
+
+export { FsStore, type FsStoreOptions, defaultFsRoot };

package/dist/internal/cache/fs.d.ts

@@ -0,0 +1,57 @@
+/** 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>;
+}
+
+declare function defaultFsRoot(): string;
+interface FsStoreOptions {
+    /** Override root directory. Defaults to {@link defaultFsRoot}. */
+    readonly root?: string;
+}
+/**
+ * Node-side CacheStore. Each key maps to one JSON file under the root.
+ */
+declare class FsStore implements CacheStore {
+    #private;
+    constructor(opts?: FsStoreOptions);
+    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 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).
+     */
+    listKeys(prefix: string): Promise<ReadonlyArray<string>>;
+    withLock<T>(key: string, fn: () => Promise<T>): Promise<T>;
+}
+
+export { FsStore, type FsStoreOptions, defaultFsRoot };

package/dist/internal/cache/fs.mjs

@@ -0,0 +1,179 @@
+// 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");
+}
+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,
+  defaultFsRoot
+};
+//# sourceMappingURL=fs.mjs.map

package/dist/internal/cache/fs.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":[]}