@dbx-tools/model 0.9.118 → 0.9.119

package/src/metadata-cache.ts

@@ -1,72 +1,29 @@
 /**
- * Agnostic daily metadata cache on {@link https://www.npmjs.com/package/cacache | cacache}.
- *
- * Uses cacache's built-in memory memoization (`memoize: true` on put; gets read
- * the in-memory layer by default) with content-addressed disk under
- * `env-paths("dbx-tools").cache/model-gateway/<version>/`. Disk persistence is
- * disabled inside a Databricks App ({@link environmentUtils.isDatabricksAppEnv});
- * those processes keep a process-local Map only.
- *
- * Each cache owns a key, hard-coded fallback, optional network loader, and a
- * merger that combines fresh / previous / fallback values. Freshness is the
- * envelope `refreshedAt` window (default one day), not cacache's short LRU TTL.
+ * Daily model metadata cache built on the shared memory-first cache package.
  *
  * @module
  */
 
-import { resolve } from "node:path";
-
-import * as environmentUtils from "@dbx-tools/shared-core/environment-utils";
+import { createCache, getOrSet } from "@dbx-tools/cache/cache";
 import * as log from "@dbx-tools/shared-core/log";
-import cacache from "cacache";
-import envPaths from "env-paths";
 
-import packageManifest from "../package.json" with { type: "json" };
+import { modelMetadataCache } from "./_cache.ts";
 import { MODEL_METADATA_TTL_MS } from "./_metadata-contract.ts";
 
 const logger = log.logger("model/metadata-cache");
 
-interface PackageIdentity {
-  readonly identifier: string;
-  readonly version: string;
-}
-
-const PACKAGE_IDENTITY: PackageIdentity = {
-  identifier: packageManifest.name,
-  version: packageManifest.version,
-};
-
-/** Envelope stored as JSON bytes in cacache for every key. */
-export interface MetadataCacheRecord<T> {
-  readonly refreshedAt: number;
-  readonly value: T;
-}
-
 /** Factory inputs for one named metadata cache. */
 export interface MetadataCacheOptions<T> {
-  /** Stable cacache key. */
+  /** Stable cache key. */
   readonly key: string;
   /** Hard-coded / committed baseline used when store and load both miss. */
   readonly fallback: T;
-  /**
-   * Refresh source. When omitted the cache only serves store + fallback and
-   * {@link MetadataCache.update} mutations (for example error-learned values).
-   */
+  /** Optional refresh source. */
   readonly load?: () => Promise<T>;
   /** Combine a fresh load, prior store value, and the hard-coded fallback. */
   readonly merge: (input: MetadataCacheMergeInput<T>) => T;
-  /** Freshness window; defaults to {@link MODEL_METADATA_TTL_MS} (one day). */
+  /** Freshness window; defaults to one day. */
   readonly ttlMs?: number;
-  /** Package version segment in the cache path. Defaults to this package. */
-  readonly version?: string;
-  /** Override the cacache root directory (tests). */
-  readonly cacheDir?: string;
-  /**
-   * Force disk on/off. Defaults to off inside Databricks Apps, on otherwise.
-   */
-  readonly disk?: boolean;
-  /** Clock override for tests. */
-  readonly now?: () => number;
 }
 
 /** Arguments passed to a cache merger. */
@@ -76,15 +33,11 @@ export interface MetadataCacheMergeInput<T> {
   readonly fallback: T;
 }
 
-/** One versioned metadata cache (cacache memory + optional disk). */
+/** One namespaced view over the shared metadata cache. */
 export interface MetadataCache<T> {
-  /** Absolute cacache root for this package version (unused when disk is off). */
-  readonly path: string;
-  /** Whether cacache disk persistence is enabled for this instance. */
-  readonly diskEnabled: boolean;
   /** Return a fresh-or-fallback value, refreshing when stale. */
   get(): Promise<T>;
-  /** Read memory / disk without refreshing. */
+  /** Read process memory without refreshing. */
   peek(): Promise<T | undefined>;
   /** Mutate the cached value and persist it. */
   update(mutator: (current: T) => T): Promise<T>;
@@ -92,161 +45,65 @@ export interface MetadataCache<T> {
   refresh(): Promise<T>;
 }
 
-const inflight = new Map<string, Promise<unknown>>();
-
-/** Default cacache root for a package version under the dbx-tools cache dir. */
-export function defaultMetadataCacheDir(version: string): string {
-  const cacheDirectory = envPaths("dbx-tools", { suffix: "" }).cache;
-  return resolve(cacheDirectory, "model-gateway", version);
-}
-
-/** Whether metadata caches should persist to disk in this process. */
-export function metadataCacheDiskEnabled(environment: NodeJS.ProcessEnv = process.env): boolean {
-  return !environmentUtils.isDatabricksAppEnv(environment);
-}
-
-/**
- * Create one daily cache backed by cacache memoization, with optional disk.
- */
-export function createMetadataCache<T>(options: MetadataCacheOptions<T>): MetadataCache<T> {
+/** Create one namespaced view over the shared model metadata cache. */
+export function createMetadataCache<T>(
+  options: MetadataCacheOptions<T>,
+  cache: ReturnType<typeof createCache> = modelMetadataCache,
+): MetadataCache<T> {
   const ttlMs = options.ttlMs ?? MODEL_METADATA_TTL_MS;
-  const diskEnabled = options.disk ?? metadataCacheDiskEnabled();
-  const now = options.now ?? Date.now;
-  const pathPromise = resolveCacheDir(options);
-  let path = options.cacheDir;
-
-  const flightKey = (cachePath: string, suffix = ""): string =>
-    `${cachePath}::${options.key}${suffix}`;
-
-  /** Process-local store used when disk is off (Databricks Apps). */
-  const memoryOnly = new Map<string, MetadataCacheRecord<T>>();
-
-  const resolveValue = (input: MetadataCacheMergeInput<T>): T => options.merge(input);
-
-  const isFresh = (record: MetadataCacheRecord<T> | undefined): boolean =>
-    Boolean(record && now() - record.refreshedAt < ttlMs);
-
-  const cachePath = async (): Promise<string> => {
-    path ??= await pathPromise;
-    return path;
-  };
+  const valueKey = `model-metadata:value:${options.key}`;
+  const refreshKey = `model-metadata:refresh:${options.key}`;
 
-  const readRecord = async (): Promise<MetadataCacheRecord<T> | undefined> => {
-    if (!diskEnabled) return memoryOnly.get(options.key);
-    const resolvedPath = await cachePath();
-    try {
-      // cacache reads its in-memory memo first unless memoize is false
-      const entry = await cacache.get(resolvedPath, options.key);
-      return decodeRecord<T>(entry.data);
-    } catch (error) {
-      if (isCacheMiss(error)) return undefined;
-      logger.warn("metadata cache cacache read failed", {
-        key: options.key,
-        path: resolvedPath,
-        error,
-      });
-      return undefined;
-    }
-  };
-
-  const writeRecord = async (record: MetadataCacheRecord<T>): Promise<void> => {
-    if (!diskEnabled) {
-      memoryOnly.set(options.key, record);
-      return;
-    }
-    const resolvedPath = await cachePath();
-    try {
-      await cacache.put(resolvedPath, options.key, `${JSON.stringify(record)}\n`, {
-        memoize: true,
-        metadata: { refreshedAt: record.refreshedAt },
-      });
-    } catch (error) {
-      logger.warn("metadata cache cacache write failed", {
-        key: options.key,
-        path: resolvedPath,
-        error,
-      });
-    }
-  };
-
-  const persist = async (value: T, refreshedAt = now()): Promise<T> => {
-    await writeRecord({ refreshedAt, value });
+  const read = (): Promise<T | undefined> => cache.get<T>(valueKey);
+  const persist = async (value: T): Promise<T> => {
+    await cache.set(valueKey, value);
     return value;
   };
+  const resolveValue = (fresh: T | undefined, previous: T | undefined): T =>
+    options.merge({ fresh, previous, fallback: options.fallback });
 
   const refresh = async (force: boolean): Promise<T> => {
-    const resolvedPath = await cachePath();
-    return coalesce(flightKey(resolvedPath), async () => {
-      const previous = await readRecord();
-      if (!force && isFresh(previous)) {
-        return resolveValue({
-          fresh: undefined,
-          previous: previous?.value,
-          fallback: options.fallback,
-        });
-      }
-
-      let fresh: T | undefined;
-      if (options.load) {
-        try {
-          fresh = await options.load();
-        } catch (error) {
-          logger.warn("metadata cache refresh failed; keeping last known good", {
-            key: options.key,
-            error,
-            path: resolvedPath,
-            diskEnabled,
-          });
+    if (force) await cache.delete(refreshKey);
+    let staleRefreshFailed = false;
+    await getOrSet(
+      cache,
+      refreshKey,
+      async () => {
+        const previous = await read();
+        let fresh: T | undefined;
+        if (options.load) {
+          try {
+            fresh = await options.load();
+          } catch (error) {
+            logger.warn("metadata cache refresh failed; using cached or committed value", {
+              key: options.key,
+              error,
+            });
+            staleRefreshFailed = previous !== undefined;
+          }
         }
-      }
-
-      const value = resolveValue({
-        fresh,
-        previous: previous?.value,
-        fallback: options.fallback,
-      });
-      if (fresh !== undefined || !previous) {
-        await persist(value);
-      }
-      return value;
-    });
+        const resolved = resolveValue(fresh, previous);
+        if (fresh !== undefined || previous === undefined) await persist(resolved);
+        return true;
+      },
+      { ttl: ttlMs, throwErrors: true },
+    );
+    if (staleRefreshFailed) await cache.delete(refreshKey);
+    return resolveValue(undefined, await read());
   };
 
   return {
-    get path() {
-      if (!path) {
-        throw new Error("metadata cache path is not resolved until the first cache read");
-      }
-      return path;
-    },
-    diskEnabled,
     get: () => refresh(false),
-    peek: async () => (await readRecord())?.value,
+    peek: read,
     refresh: () => refresh(true),
     update: async (mutator) => {
-      const resolvedPath = await cachePath();
-      return coalesce(flightKey(resolvedPath, ":update"), async () => {
-        const previous = await readRecord();
-        const baseline = resolveValue({
-          fresh: undefined,
-          previous: previous?.value,
-          fallback: options.fallback,
-        });
-        return persist(mutator(baseline));
-      });
+      const value = await persist(mutator(resolveValue(undefined, await read())));
+      await cache.set(refreshKey, true, { ttl: ttlMs });
+      return value;
     },
   };
 }
 
-async function resolveCacheDir(options: {
-  readonly cacheDir?: string;
-  readonly version?: string;
-}): Promise<string> {
-  if (options.cacheDir) return options.cacheDir;
-  const version = options.version ?? PACKAGE_IDENTITY.version;
-  return defaultMetadataCacheDir(version);
-}
-
 /** Prefer a non-empty fresh array, else previous, else fallback. */
 export function mergePreferFreshList<T>(input: MetadataCacheMergeInput<readonly T[]>): T[] {
   if (input.fresh && input.fresh.length > 0) return [...input.fresh];
@@ -254,10 +111,7 @@ export function mergePreferFreshList<T>(input: MetadataCacheMergeInput<readonly
   return [...input.fallback];
 }
 
-/**
- * Shallow-merge record catalogues: fallback, then previous, then fresh keys.
- * Fresh values win per key.
- */
+/** Shallow-merge record catalogues: fallback, then previous, then fresh keys. */
 export function mergePreferFreshRecord<T>(
   input: MetadataCacheMergeInput<Readonly<Record<string, T>>>,
 ): Record<string, T> {
@@ -267,51 +121,3 @@ export function mergePreferFreshRecord<T>(
     ...(input.fresh ?? {}),
   };
 }
-
-/** Test helper: wipe a cacache root and clear cacache memoization. */
-export async function resetMetadataCacheDir(cacheDir: string): Promise<void> {
-  try {
-    await cacache.rm.all(cacheDir);
-  } catch {
-    // empty / missing cache is fine
-  }
-  cacache.clearMemoized();
-  for (const key of [...inflight.keys()]) {
-    if (key.startsWith(`${cacheDir}::`)) inflight.delete(key);
-  }
-}
-
-function coalesce<T>(key: string, work: () => Promise<T>): Promise<T> {
-  const existing = inflight.get(key);
-  if (existing) return existing as Promise<T>;
-  const pending = work().finally(() => {
-    if (inflight.get(key) === pending) inflight.delete(key);
-  });
-  inflight.set(key, pending);
-  return pending;
-}
-
-function decodeRecord<T>(data: Buffer): MetadataCacheRecord<T> | undefined {
-  try {
-    const parsed = JSON.parse(data.toString("utf8")) as unknown;
-    if (
-      !parsed ||
-      typeof parsed !== "object" ||
-      typeof (parsed as MetadataCacheRecord<T>).refreshedAt !== "number"
-    ) {
-      return undefined;
-    }
-    return parsed as MetadataCacheRecord<T>;
-  } catch {
-    return undefined;
-  }
-}
-
-function isCacheMiss(error: unknown): boolean {
-  return Boolean(
-    error &&
-    typeof error === "object" &&
-    "code" in error &&
-    (error as { code?: string }).code === "ENOENT",
-  );
-}

package/src/metadata.ts

@@ -4,9 +4,10 @@
  * docs and error-learned reasoning ladders.
  *
  * Committed snapshots seed every process. {@link refreshModelMetadata} pulls
- * documentation through {@link createMetadataCache} (cacache memoize + disk) and
+ * documentation through the shared memory-first {@link createMetadataCache} and
  * rebuilds the in-memory index. Error-learned efforts use the same store via
- * {@link rememberReasoningLevels}. Disk writes are skipped in Databricks Apps.
+ * {@link rememberReasoningLevels}. Known-good values are written behind to the
+ * shared model project cache.
  *
  * @module
  */
@@ -251,7 +252,7 @@ export async function refreshModelMetadata(): Promise<MetadataIndex> {
   return refreshInflight;
 }
 
-/** Load cacache / memory entries without forcing a network refresh. */
+/** Load shared cache entries without forcing a network refresh. */
 export async function hydrateModelMetadata(): Promise<MetadataIndex> {
   const [retiredNames, capabilities, rateLimits, reasoning, learnedReasoning] = await Promise.all([
     peekOrFallback(retiredCache, COMMITTED_RETIRED_MODELS),
@@ -276,11 +277,6 @@ async function peekOrFallback<T>(cache: MetadataCache<T>, fallback: T): Promise<
   return cache.get().catch(() => fallback);
 }
 
-/** Absolute cacache root used by the documentation / learned caches. */
-export function modelMetadataCachePath(): string {
-  return retiredCache.path;
-}
-
 export { modelStatusFor, retiredModelNames } from "./_retirement.ts";
 
 /** Return the committed reasoning-effort catalogue. Cached per process. */
@@ -288,7 +284,7 @@ export function reasoningModelCatalogue(): ReasoningModelCatalogue {
   return metadataIndex().reasoning;
 }
 
-/** Return error-learned reasoning ladders persisted in the metadata cache. */
+/** Return error-learned reasoning ladders from the shared model cache. */
 export function learnedReasoningCatalogue(): ReasoningModelCatalogue {
   return metadataIndex().learnedReasoning;
 }
@@ -324,7 +320,7 @@ export async function rememberReasoningLevels(
  *
  * Accepts the same nested Databricks envelopes as {@link parseReasoningLevels}.
  * Returns the levels that were stored (or the current lookup when parse yields
- * nothing). The raw error body is never written to disk.
+ * nothing). The raw error body is never cached.
  */
 export async function learnReasoningLevelsFromError(
   model: string,

package/src/model-catalog.ts

@@ -3,7 +3,7 @@
  *
  * Lists the workspace's `/serving-endpoints` and, when the caller supplies a
  * trusted credential identity, caches the result per host and identity with a
- * TTL via AppKit's `CacheManager`. Concurrent callers in the same scope share
+ * TTL via `@dbx-tools/cache`. Concurrent callers in the same scope share
  * one in-flight promise. Surfaces each endpoint as a stable
  * {@link ServingEndpointSummary} - including the Foundation Model API
  * `quality` / `speed` / `cost` profile when present, the classified
@@ -22,8 +22,8 @@
  */
 
 import { createHash } from "node:crypto";
-import { CacheManager } from "@databricks/appkit";
 import { appkit } from "@dbx-tools/appkit";
+import { deleteCachedValue, getOrSet } from "@dbx-tools/cache/cache";
 import { errorUtils, log } from "@dbx-tools/shared-core";
 import {
   model,
@@ -33,6 +33,7 @@ import {
   type ServingEndpointSummary,
 } from "@dbx-tools/shared-model";
 
+import { modelCatalogueCache } from "./_cache.ts";
 import { classifyEndpointClasses, normalizeEndpoints, rankEndpoints } from "./_ranking.ts";
 
 const { ModelClass } = model;
@@ -54,12 +55,12 @@ export const DEFAULT_FUZZY_THRESHOLD = 0.4;
 
 /** Cache key parts under which endpoint listings are stored. */
 const CACHE_KEY_NAMESPACE = "serving-endpoints";
+const catalogueCache = modelCatalogueCache;
 
 /** Options for {@link listServingEndpoints}. */
 export interface ListServingEndpointsOptions {
   /**
-   * Override the default cache TTL for this call, in milliseconds. Forwarded to
-   * `CacheManager` as seconds.
+   * Override the default cache TTL for this call, in milliseconds.
    */
   ttlMs?: number;
   /**
@@ -73,30 +74,23 @@ export interface ListServingEndpointsOptions {
   cacheIdentity?: string;
 }
 
-/** Hash an opaque credential identity before handing it to CacheManager. */
+/** Hash an opaque credential identity before handing it to the shared cache. */
 function cacheUserKey(identity: string): string {
   return `model-${createHash("sha256").update(identity).digest("hex")}`;
 }
 
 /**
  * List Model Serving endpoints for the workspace owning `client`, routed
- * through AppKit's `CacheManager`. The manager gives us everything
- * `cachetools.TTLCache` provides plus what `cachetools-async` adds on top:
- * per-entry TTL, in-flight request coalescing (concurrent callers share one
- * fetch via the manager's internal `inFlightRequests` map), bounded size,
- * telemetry spans (`cache.getOrExecute`), and optional Lakebase persistence so
- * the catalogue survives restarts when the lakebase plugin is wired up.
+ * through the shared memory-first cache, including per-entry TTL, in-flight
+ * request coalescing, bounded process memory, and portable persistence.
  *
  * Returns plain {@link ServingEndpointSummary} objects (a stable subset of the
- * SDK type) so cache hits never expose stale SDK internals. Errors from
- * `CacheManager` or the SDK fetch propagate to the caller - we don't swallow
- * them so users see the real auth / network issue.
+ * SDK type) so cache hits never expose stale SDK internals.
  *
  * @param host - Workspace host used as the cache key. Pass the value resolved
  *   from `client.config.getHost()` so multi-host apps share one entry per
  *   workspace.
- * @param options.ttlMs - Override the default TTL just for this call. Forwarded
- *   to `CacheManager` as seconds.
+ * @param options.ttlMs - Override the default TTL just for this call.
  */
 export async function listServingEndpoints(
   client: WorkspaceClientLike,
@@ -104,13 +98,17 @@ export async function listServingEndpoints(
   options: ListServingEndpointsOptions = {},
 ): Promise<ServingEndpointSummary[]> {
   if (!options.cacheIdentity) return fetchEndpoints(client);
-  const ttlSec = Math.max(1, Math.round((options.ttlMs ?? DEFAULT_MODEL_CACHE_TTL_MS) / 1000));
-  return CacheManager.getInstanceSync().getOrExecute(
-    [CACHE_KEY_NAMESPACE, host],
+  return (await getOrSet(
+    catalogueCache,
+    catalogueCacheKey(host, options.cacheIdentity),
     () => fetchEndpoints(client),
-    cacheUserKey(options.cacheIdentity),
-    { ttl: ttlSec },
-  );
+    {
+      ttl: options.ttlMs ?? DEFAULT_MODEL_CACHE_TTL_MS,
+      returnCachedOnError: true,
+      cachedOnErrorTtl: "7d",
+      throwErrors: true,
+    },
+  ))!;
 }
 
 /**
@@ -119,7 +117,7 @@ export async function listServingEndpoints(
  * none of the cache-load enrichment ({@link listServingEndpoints} adds the
  * {@link ModelClass} stamp and the embedding-dimension probe). Use this for a
  * one-shot, dependency-light listing - e.g. a CLI that only needs names/tasks
- * for fuzzy resolution and doesn't want AppKit's `CacheManager` or the
+ * for fuzzy resolution and doesn't want shared cache persistence or the
  * per-embedding ping cost. Prefer {@link listServingEndpoints} for the cached,
  * enriched view.
  */
@@ -197,24 +195,24 @@ async function pingEmbeddingDimension(
 }
 
 /**
- * Force-evict cached endpoint listings via AppKit's `CacheManager`. A host and
- * identity delete only that principal's workspace entry. Because CacheManager
- * cannot enumerate a namespace, omitting either value clears the complete
- * manager and should be reserved for tests or administrative refreshes.
+ * Force-evict cached endpoint listings. A host and identity delete only that
+ * principal's workspace entry. Omitting either value clears this catalogue.
  */
 export async function clearServingEndpointsCache(
   host?: string,
   cacheIdentity?: string,
 ): Promise<void> {
-  const cache = CacheManager.getInstanceSync();
   if (host && cacheIdentity) {
-    const key = cache.generateKey([CACHE_KEY_NAMESPACE, host], cacheUserKey(cacheIdentity));
-    await cache.delete(key);
+    await deleteCachedValue(catalogueCache, catalogueCacheKey(host, cacheIdentity));
   } else {
-    await cache.clear();
+    await catalogueCache.clear();
   }
 }
 
+function catalogueCacheKey(host: string, cacheIdentity: string): string {
+  return JSON.stringify([CACHE_KEY_NAMESPACE, host, cacheUserKey(cacheIdentity)]);
+}
+
 /**
  * Result of fuzzy-resolving a user-supplied model name against the live
  * endpoint list. `score` is the ranker's distance (`0` is exact, `1` is no match);