audit-tools 0.34.41 → 0.35.0

package/dist/shared/providers/proxyCatalog.js

@@ -1,658 +0,0 @@
-import { readFileSync } from "node:fs";
-import { mkdir } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { writeJsonFile } from "../io/json.js";
-import { resolveAuditCodeStateDir } from "../io/stateDir.js";
-import { validateSessionConfig } from "../validation/sessionConfig.js";
-/**
- * The POPULATE cache for the proxy lane: discovered via `GET <proxy>/v1/models` +
- * `GET <proxy>/model/info` (OpenAI-compatible surfaces) expanded into ready-to-fold
- * `claude-worker` {@link DispatchableSource}s, written once per populate (Gate-0 build
- * / explicit refresh) and READ by resolve — never fetched mid-resolve.
- *
- * Named `catalog-cache.json`, NOT the `catalog-<auditor-id>.json` the reserved-name
- * comment at `auditorSources.ts` anticipates: populate/resolve run on the AMBIENT
- * path, where no auditor id exists to key on. The cache is machine-level like the
- * declaration beside it — and it is a CACHE of live discovery state, not resolved
- * per-auditor capability, so an auditor-id key would assert an isolation the data
- * doesn't have. Per-auditor never-inherit still holds: every resolve re-proves proxy
- * REACH itself; the cache only supplies the expansion.
- */
-export const PROXY_CATALOG_FILENAME = "catalog-cache.json";
-/** Top-K models expanded per backend provider when the operator declares no `top_k`. */
-export const DEFAULT_PROXY_TOP_K = 3;
-/**
- * USD-per-token → USD-per-million-tokens conversion factor. LiteLLM
- * `/model/info` advertises `input_cost_per_token` / `output_cost_per_token`
- * per TOKEN; the `cost_per_mtok` source field is per MILLION tokens
- * (INV-SCC-03 unit discipline).
- */
-const PER_TOKEN_TO_PER_MTOK = 1_000_000;
-/** Timeout (ms) for populate-time model verification probes. */
-export const POPULATE_PROBE_TIMEOUT_MS = 3000;
-/** Concurrency limit for populate-time model verification probes. */
-export const POPULATE_PROBE_CONCURRENCY = 4;
-/**
- * A same-endpoint cache younger than this skips the registry fetch + probes
- * entirely (see the freshness short-circuit in {@link populateProxyCatalog}).
- * Refresh THROTTLE — how often we are willing to PAY for a refresh, which is a
- * different question from how long an unrefreshed cache may still be believed
- * ({@link PROXY_CATALOG_MAX_READ_AGE_MS}). The two thresholds share one age
- * derivation and nothing else.
- */
-export const POPULATE_CACHE_FRESH_TTL_MS = 10 * 60_000;
-/**
- * Past this age a cache is returned STALE by {@link readProxyCatalog} — the
- * expansion still travels, with a verdict attached, so the caller decides rather
- * than consuming an unbounded-age cache blind.
- *
- * A day: comfortably longer than any single run (a mid-run flip to stale would be
- * churn, not signal), and short enough that a roster the operator changed — a model
- * added to or dropped from the proxy config — cannot go unnoticed indefinitely.
- * The cache is machine-global and tool-written, so being wrong here costs one
- * repopulate, never data.
- */
-export const PROXY_CATALOG_MAX_READ_AGE_MS = 24 * 60 * 60_000;
-/** Resolve the populate-cache path for this machine (state dir via `io/stateDir.ts`). */
-export function resolveProxyCatalogPath(homeDir) {
-    return join(resolveAuditCodeStateDir(homeDir), PROXY_CATALOG_FILENAME);
-}
-/**
- * Shape version of the on-disk cache. Bump whenever a written entry's meaning changes,
- * so a cache written by older code degrades to "absent" rather than being read under
- * new semantics. The cache is tool-written and fully regenerable, so degrading is free —
- * `readProxyCatalog` returns null, and `populateProxyCatalogIfMissing` then repopulates.
- *
- * v2: entries no longer carry a tool-stamped `id`. A v1 entry does, and since `id` now
- * outranks the `service` derivation in `dispatchableSourceId`, reading one under v2
- * semantics would key a proxied lane to `claude-worker:<service>/<model>` instead of
- * `<service>/<model>` — silently splitting it from the direct lane to the same backend
- * and reopening the double-grant boundary.
- */
-export const PROXY_CATALOG_VERSION = 2;
-function finiteNonNegative(value) {
-    return typeof value === "number" && Number.isFinite(value) && value >= 0
-        ? value
-        : undefined;
-}
-/**
- * Edge adapter: proxy `/model/info` response shape → neutral ModelAdvert contract.
- * Maps from proxy-specific field names to a generic contract.
- *
- * Returns:
- * - { advert, filtered: false | undefined } for valid models
- * - { filtered: true } for models filtered by eligibility rules
- * - undefined for invalid data (missing modelName/model_info)
- */
-function adaptProxyModelInfo(modelInfo) {
-    const modelName = modelInfo.model_name;
-    if (typeof modelName !== "string" || modelName.trim().length === 0)
-        return undefined;
-    const info = modelInfo.model_info;
-    if (info === null || typeof info !== "object")
-        return undefined;
-    const infoObj = info;
-    const proxyProvider = infoObj.litellm_provider;
-    const provider = typeof proxyProvider === "string" ? proxyProvider : undefined;
-    const mode = infoObj.mode;
-    const supportsToolCalls = infoObj.supports_tool_calls;
-    // Check eligibility: mode must be "chat" or absent (unknown ≠ incapable).
-    // supports_tool_calls false → skip; absent or true → keep.
-    if (typeof mode === "string" && mode !== "chat")
-        return { filtered: true };
-    if (supportsToolCalls === false)
-        return { filtered: true };
-    return {
-        advert: {
-            alias: modelName.trim(),
-            ...(provider !== undefined ? { provider } : {}),
-            context_tokens: finiteNonNegative(infoObj.max_input_tokens),
-            input_cost_per_token: finiteNonNegative(infoObj.input_cost_per_token),
-            output_cost_per_token: finiteNonNegative(infoObj.output_cost_per_token),
-            mode: typeof mode === "string" ? mode : undefined,
-            supports_tool_calls: typeof supportsToolCalls === "boolean" ? supportsToolCalls : undefined,
-            // Operator-declared rank via advert custom key (consumed as-is when present).
-            declared_rank: finiteNonNegative(infoObj.capability_rank),
-        },
-    };
-}
-/**
- * Best-effort "higher = better" score for ranking. Uses a flat `score` field
- * when present; absent/non-finite → null (unscored models rank last).
- */
-function deriveScore(entry) {
-    if (typeof entry.score === "number" && Number.isFinite(entry.score)) {
-        return entry.score;
-    }
-    return null;
-}
-/**
- * Tolerantly extract context-window field from a registry entry or its nested
- * `capability` block. Checks for `context_length`, `context_tokens`, `max_context`,
- * `context_window` (first finite positive number wins).
- */
-function deriveContextTokens(entry) {
-    for (const key of ["context_length", "context_tokens", "max_context", "context_window"]) {
-        const value = finiteNonNegative(entry[key]);
-        if (value !== undefined)
-            return value;
-    }
-    const capability = entry.capability;
-    if (capability !== null && typeof capability === "object") {
-        for (const key of ["context_length", "context_tokens", "max_context", "context_window"]) {
-            const value = finiteNonNegative(capability[key]);
-            if (value !== undefined)
-                return value;
-        }
-    }
-    return undefined;
-}
-/**
- * Discover models via the neutral proxy contract: `GET /v1/models` (required baseline)
- * returns the alias roster; `GET /model/info` (optional enrichment) provides per-model
- * metadata. Tolerant at every step: missing/unparseable/malformed → graceful degradation.
- * Eligibility filters remove models from the pool entirely (mode != 'chat' or
- * supports_tool_calls === false).
- *
- * Returns { adverts, filtered } where adverts is a map of alias → ModelAdvert,
- * and filtered is a set of aliases that failed the eligibility filter.
- */
-async function discoverModelAdverts(endpoint, fetchImpl, authHeader) {
-    const adverts = new Map();
-    const filtered = new Set();
-    try {
-        const headers = { "content-type": "application/json" };
-        if (authHeader)
-            headers.authorization = authHeader;
-        // Try /model/info first (richer advert); tolerate absent/unparseable
-        try {
-            const response = await fetchImpl(`${endpoint}/model/info`, { headers });
-            if (response.ok) {
-                const payload = await response.json();
-                // Target the current array form: {data: [...]}
-                if (payload !== null && typeof payload === "object") {
-                    const data = payload.data;
-                    if (Array.isArray(data)) {
-                        for (const raw of data) {
-                            if (raw !== null && typeof raw === "object") {
-                                const result = adaptProxyModelInfo(raw);
-                                if (result) {
-                                    if (result.filtered) {
-                                        // Track which aliases failed the eligibility filter
-                                        const modelName = raw.model_name;
-                                        if (typeof modelName === "string" && modelName.trim().length > 0) {
-                                            filtered.add(modelName.trim());
-                                        }
-                                    }
-                                    else if (result.advert) {
-                                        // Successful adaptation
-                                        adverts.set(result.advert.alias, result.advert);
-                                    }
-                                }
-                                // If result is undefined, it's invalid data (not eligibility filter)
-                            }
-                        }
-                    }
-                }
-            }
-        }
-        catch {
-            // /model/info absent/error → degrade to roster-only (no enrichment)
-        }
-    }
-    catch {
-        // No adverts → degrade to roster-only (carrier of aliases only)
-    }
-    return { adverts, filtered };
-}
-/**
- * Discover the model roster via the neutral proxy contract: `GET /v1/models`
- * (OpenAI-compatible list). Returns { aliases, error? }; absent/unparseable → empty aliases + reason.
- */
-async function discoverModelRoster(endpoint, fetchImpl, authHeader) {
-    try {
-        const headers = { "content-type": "application/json" };
-        if (authHeader)
-            headers.authorization = authHeader;
-        const response = await fetchImpl(`${endpoint}/v1/models`, { headers });
-        if (!response.ok) {
-            return {
-                aliases: [],
-                error: `HTTP ${response.status}`,
-            };
-        }
-        const payload = await response.json();
-        if (payload === null || typeof payload !== "object")
-            return { aliases: [] };
-        const data = payload.data;
-        if (!Array.isArray(data))
-            return { aliases: [] };
-        const aliases = [];
-        for (const entry of data) {
-            if (entry !== null && typeof entry === "object") {
-                const id = entry.id;
-                if (typeof id === "string" && id.trim().length > 0) {
-                    aliases.push(id.trim());
-                }
-            }
-        }
-        return { aliases };
-    }
-    catch (err) {
-        const reason = err instanceof Error ? err.message : String(err);
-        return { aliases: [], error: reason };
-    }
-}
-/**
- * Expand discovered models into `claude-worker` sources: per backend provider,
- * the top-K models by best-effort score (higher = better; unscored last).
- * Shape per the plan's identity section: the transport never enters the identity —
- * `service` + `model` (alias) key quota; `endpoint` is the proxy url the
- * launch transport fronts the spawn with; `worker_kind` is `agentic` by definition.
- *
- * Provider derivation: advert `provider` (from /model/info) > slash-prefix of alias
- * (e.g., `anthropic/claude-*` → `anthropic`) > default shared `"proxy"` bucket
- * (coarse pool identity at degradation rung, revisitable per owner decision).
- */
-function expandSources(discovered, options) {
-    const byProvider = new Map();
-    // Dedup by (provider, alias): first row wins.
-    const seen = new Set();
-    for (const model of discovered) {
-        const identity = `${model.provider}/${model.alias}`;
-        if (seen.has(identity))
-            continue;
-        seen.add(identity);
-        const bucket = byProvider.get(model.provider) ?? [];
-        bucket.push(model);
-        byProvider.set(model.provider, bucket);
-    }
-    const sources = [];
-    const dropped = [];
-    // Stable, content-derived order (provider, then score desc, then alias) so
-    // re-populate over identical state emits byte-identical sources.
-    for (const provider of [...byProvider.keys()].sort()) {
-        const bucket = byProvider.get(provider);
-        const ordered = bucket.sort((a, b) => (b.score ?? Number.NEGATIVE_INFINITY) - (a.score ?? Number.NEGATIVE_INFINITY) ||
-            a.alias.localeCompare(b.alias));
-        const ranked = ordered.slice(0, options.topK);
-        // Truncation is never silent. With every `score` null the comparator's first
-        // term is NaN (-Infinity - -Infinity), so the sort degenerates to
-        // `localeCompare` and `top_k` keeps the ALPHABETICALLY-first models — which
-        // once kept a *flash* model and dropped every frontier one. The order still
-        // has to be deterministic (a content-derived array order is an artifact
-        // invariant), so the fix is not a different order: it is that every model
-        // top_k discards reaches the operator through the same `dropped[]` channel
-        // as an unreachable model, and says WHICH basis chose it.
-        const rankedCount = ordered.filter((m) => m.score !== null).length;
-        const basis = rankedCount === 0
-            ? `no model in this backend advertises a rank, so the cut is ALPHABETICAL, not by capability`
-            : rankedCount === ordered.length
-                ? `cut by advertised rank`
-                : `only ${rankedCount} of ${ordered.length} models advertise a rank; unranked models sort last and were cut alphabetically among themselves`;
-        for (const model of ordered.slice(options.topK)) {
-            dropped.push({
-                id: `claude-worker:${provider}/${model.alias}`,
-                reason: `top_k=${options.topK} kept ${ranked.length} of ${ordered.length} models for backend ` +
-                    `"${provider}" — ${basis}. Raise proxy.top_k, or advertise a rank, to keep it.`,
-            });
-        }
-        for (const model of ranked) {
-            // Cost precedence: operator-declared (free-to-operator axis) > advert price
-            // > absent (falls through to models.dev catalog / tier downstream).
-            const cost = options.costPerMtok ?? model.costPerMtok;
-            sources.push({
-                // No `id` stamped, deliberately. `id` is an operator OVERRIDE that outranks
-                // derivation (spec/backend-identity-axes.md); a tool-stamped transport-shaped
-                // id would claim that override and re-split the very identity `service` exists
-                // to merge — a proxied lane and a direct lane to the same service+model would
-                // key to two CapacityPools, reopening the double-grant boundary. Leaving it
-                // absent lets `dispatchableSourceId` derive `service[#account]/model`, which
-                // dedups the two lanes by construction.
-                transport: "claude-worker",
-                endpoint: options.endpoint,
-                service: provider,
-                model: model.alias, // Alias VERBATIM — the proxy's routing key
-                worker_kind: "agentic",
-                ...(options.apiKeyEnv !== undefined ? { api_key_env: options.apiKeyEnv } : {}),
-                ...(cost !== undefined ? { cost_per_mtok: cost } : {}),
-                // Step C: per-model capability (raw rank, LOWER = better) rides the source →
-                // CapacityPool.declaredCapabilityRank → the admission capability floor.
-                ...(model.capabilityRank !== undefined
-                    ? { capability_rank: model.capabilityRank }
-                    : {}),
-                ...(model.contextTokens !== undefined
-                    ? { quota: { context_tokens: model.contextTokens } }
-                    : {}),
-            });
-        }
-    }
-    return { sources, dropped };
-}
-/**
- * Probe a single model via Anthropic-compatible `/v1/messages` to verify it is
- * actually reachable. Returns { dropped: true, reason } if the model should be
- * excluded (404/unavailable), or { dropped: false } to keep it.
- */
-async function probeModelViaMessages(alias, backendProvider, endpoint, fetchImpl, timeoutMs, authHeader) {
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
-    try {
-        const headers = {
-            "anthropic-version": "2023-06-01",
-            "content-type": "application/json",
-        };
-        if (authHeader)
-            headers.authorization = authHeader;
-        const response = await fetchImpl(`${endpoint}/v1/messages`, {
-            method: "POST",
-            headers,
-            body: JSON.stringify({
-                model: alias, // Route on proxy alias, not backend namespace
-                max_tokens: 1,
-                messages: [{ role: "user", content: "hi" }],
-            }),
-            signal: controller.signal,
-        });
-        // Check for 404 or model-not-found patterns
-        if (response.status === 404) {
-            return { dropped: true, reason: "HTTP 404" };
-        }
-        if (response.status >= 400) {
-            let bodyText = "";
-            try {
-                bodyText = await response.text();
-            }
-            catch {
-                // If body read fails, just use status code
-            }
-            const patterns = [/model_not_found/i, /\bmay not exist\b/i, /no such model/i];
-            if (patterns.some((p) => p.test(bodyText))) {
-                return { dropped: true, reason: `HTTP ${response.status} (model unavailable)` };
-            }
-        }
-        // 200, 401, 429, 5xx, etc. → keep the model
-        return { dropped: false };
-    }
-    catch (error) {
-        // Transport failure (timeout, network error) → fail-open, keep the model
-        return { dropped: false };
-    }
-    finally {
-        clearTimeout(timeoutId);
-    }
-}
-/**
- * Probe models with bounded concurrency using a simple worker pool.
- */
-async function probeModelsWithConcurrency(aliases, backendProvider, endpoint, fetchImpl, timeoutMs, concurrency, authHeader) {
-    const results = [];
-    let index = 0;
-    const worker = async () => {
-        while (index < aliases.length) {
-            const currentIndex = index++;
-            const alias = aliases[currentIndex];
-            const probeResult = await probeModelViaMessages(alias, backendProvider, endpoint, fetchImpl, timeoutMs, authHeader);
-            results[currentIndex] = {
-                alias,
-                dropped: probeResult.dropped,
-                reason: probeResult.reason,
-            };
-        }
-    };
-    const workers = Array(Math.min(concurrency, aliases.length))
-        .fill(null)
-        .map(() => worker());
-    await Promise.all(workers);
-    // results is index-assigned, so already in order.
-    return results;
-}
-/**
- * POPULATE: discover and expand models from an OpenAI-compatible proxy
- * (`GET <endpoint>/v1/models` + `GET <endpoint>/model/info`) into
- * ready-to-fold `claude-worker` sources, then write to the machine-level cache.
- * Network-bound and cacheable — runs at Gate-0 build / explicit refresh, NEVER
- * inside `resolveAmbientSources` (which only READS via {@link readProxyCatalog}).
- * Never throws: a failed fetch returns `{written:false, reason}` and leaves any
- * prior cache untouched; an empty discovery WRITES an empty expansion (fresh
- * knowledge — resolve reports the lane unexpanded with a reason).
- */
-export async function populateProxyCatalog(options) {
-    const endpoint = options.endpoint.replace(/\/+$/u, "");
-    const doFetch = options.fetchImpl ?? fetch;
-    // Build auth header when api_key_env is declared and the env var is set.
-    let authHeader;
-    if (options.apiKeyEnv) {
-        const keyValue = process.env[options.apiKeyEnv];
-        if (keyValue?.trim()) {
-            authHeader = `Bearer ${keyValue}`;
-        }
-    }
-    // Freshness short-circuit: populate carries live per-model probes — real
-    // `/v1/messages` POSTs through the proxy that cost seconds and burn quota.
-    // A same-endpoint cache younger than the TTL answers instead. This is a
-    // REFRESH throttle, a tighter window than the read-side staleness bound;
-    // the age itself comes from the ONE derivation in `readProxyCatalog` (on this
-    // call's clock), so the two thresholds can never disagree about how old a file is.
-    const cached = readProxyCatalog({ homeDir: options.homeDir, now: options.now });
-    if (cached &&
-        cached.endpoint === endpoint &&
-        cached.age_ms >= 0 &&
-        cached.age_ms < POPULATE_CACHE_FRESH_TTL_MS) {
-        return {
-            sources: cached.sources,
-            written: false,
-            reason: `cache is fresh (fetched ${Math.round(cached.age_ms / 1000)}s ago); refresh skipped.`,
-            dropped: [],
-        };
-    }
-    // Discover model roster (required baseline: /v1/models).
-    const { aliases, error: rosterError } = await discoverModelRoster(endpoint, doFetch, authHeader);
-    if (aliases.length === 0) {
-        return {
-            sources: [],
-            written: false,
-            reason: rosterError
-                ? `GET ${endpoint}/v1/models failed: ${rosterError}`
-                : `GET ${endpoint}/v1/models returned no models or was unreachable.`,
-            dropped: [],
-        };
-    }
-    // Discover model adverts (optional enrichment: /model/info).
-    const { adverts, filtered } = await discoverModelAdverts(endpoint, doFetch, authHeader);
-    // Build discovered models: join roster + adverts, deriving provider.
-    const discovered = [];
-    for (const alias of aliases) {
-        // Skip models that failed the eligibility filter
-        if (filtered.has(alias))
-            continue;
-        const advert = adverts.get(alias);
-        // Provider derivation: advert provider > slash-prefix > default "proxy" bucket.
-        let provider;
-        if (advert?.provider) {
-            provider = advert.provider;
-        }
-        else if (alias.includes("/")) {
-            provider = alias.split("/")[0];
-        }
-        else {
-            provider = "proxy";
-        }
-        // Cost blend: mean of input/output when both present; otherwise the one
-        // present. UNIT DISCIPLINE (INV-SCC-03 / COR-6c1ad0ba): the advert fields
-        // (`input_cost_per_token` / `output_cost_per_token`, LiteLLM /model/info
-        // convention) are USD per TOKEN; `cost_per_mtok`'s contract is USD per
-        // MILLION tokens, so the blend converts ×1e6. Writing the per-token value
-        // straight through underprices every proxied lane 1,000,000x and lets it
-        // incorrectly dominate cost-first routing.
-        const availableCosts = [];
-        if (advert?.input_cost_per_token !== undefined) {
-            availableCosts.push(advert.input_cost_per_token * PER_TOKEN_TO_PER_MTOK);
-        }
-        if (advert?.output_cost_per_token !== undefined) {
-            availableCosts.push(advert.output_cost_per_token * PER_TOKEN_TO_PER_MTOK);
-        }
-        let costPerMtok;
-        if (availableCosts.length === 2) {
-            costPerMtok = (availableCosts[0] + availableCosts[1]) / 2;
-        }
-        else if (availableCosts.length === 1) {
-            costPerMtok = availableCosts[0];
-        }
-        discovered.push({
-            alias,
-            provider,
-            score: advert?.declared_rank !== undefined ? -advert.declared_rank : null,
-            capabilityRank: advert?.declared_rank,
-            costPerMtok,
-            contextTokens: advert?.context_tokens,
-        });
-    }
-    // Probe to verify models are reachable and drop 404s.
-    // Group by provider for parallel probing per provider.
-    const byProvider = new Map();
-    for (const model of discovered) {
-        const bucket = byProvider.get(model.provider) ?? [];
-        bucket.push(model.alias);
-        byProvider.set(model.provider, bucket);
-    }
-    const droppedAliases = new Set();
-    const dropped = [];
-    for (const [provider, providerAliases] of byProvider) {
-        const probeResults = await probeModelsWithConcurrency(providerAliases, provider, endpoint, doFetch, POPULATE_PROBE_TIMEOUT_MS, POPULATE_PROBE_CONCURRENCY, authHeader);
-        for (const result of probeResults) {
-            if (result.dropped) {
-                droppedAliases.add(result.alias);
-                dropped.push({
-                    id: `claude-worker:${provider}/${result.alias}`,
-                    reason: result.reason ?? "model unavailable",
-                });
-            }
-        }
-    }
-    // Filter out dropped models and expand sources.
-    const toExpand = discovered.filter((m) => !droppedAliases.has(m.alias));
-    const expanded = expandSources(toExpand, {
-        endpoint,
-        topK: options.topK ?? DEFAULT_PROXY_TOP_K,
-        costPerMtok: options.costPerMtok,
-        apiKeyEnv: options.apiKeyEnv,
-    });
-    const sources = expanded.sources;
-    // top_k truncation joins the unreachable-model drops in the ONE operator-facing
-    // channel, so "the frontier model isn't there" always carries its reason.
-    dropped.push(...expanded.dropped);
-    const catalog = {
-        version: PROXY_CATALOG_VERSION,
-        fetched_at: (options.now?.() ?? new Date()).toISOString(),
-        endpoint,
-        sources,
-    };
-    const path = resolveProxyCatalogPath(options.homeDir);
-    try {
-        await mkdir(dirname(path), { recursive: true });
-        await writeJsonFile(path, catalog);
-    }
-    catch (error) {
-        return {
-            sources,
-            written: false,
-            reason: `could not write ${path}: ${error instanceof Error ? error.message : String(error)}.`,
-            dropped,
-        };
-    }
-    return { sources, written: true, dropped };
-}
-function defaultReadCatalogFile(path) {
-    try {
-        return readFileSync(path, "utf8");
-    }
-    catch {
-        return null;
-    }
-}
-/** Human-readable magnitude for an age/skew, in the largest unit that still reads. */
-function describeAgeMs(ms) {
-    const abs = Math.abs(ms);
-    if (abs < 90 * 60_000)
-        return `${Math.round(abs / 60_000)}m`;
-    if (abs < 48 * 3_600_000)
-        return `${(abs / 3_600_000).toFixed(1)}h`;
-    return `${(abs / 86_400_000).toFixed(1)}d`;
-}
-/**
- * READ the populate cache, with the read-side age rule applied: every result carries
- * `age_ms` and a `stale` verdict against {@link PROXY_CATALOG_MAX_READ_AGE_MS}, so an
- * old cache reaches its caller labelled rather than indistinguishable from a fresh one.
- * Degrades to `null` on absent / unparseable / structurally-invalid content — never
- * throws (same bar as `readSourceDeclaration`: the resolve path must not be failable by
- * a bad file). Cached sources are held to the shared source validator, so a hand-edited
- * or version-skewed cache degrades to "no cache" rather than admitting a half-checked
- * pool.
- */
-export function readProxyCatalog(deps = {}) {
-    const path = resolveProxyCatalogPath(deps.homeDir);
-    const raw = (deps.readCatalogFile ?? defaultReadCatalogFile)(path);
-    if (raw === null)
-        return null;
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        return null;
-    }
-    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-        return null;
-    }
-    const { version, fetched_at, endpoint, sources } = parsed;
-    // Degrade a foreign-shape cache to "absent" rather than reading it under current
-    // semantics. A pre-versioned (v1) file carries tool-stamped ids that would now
-    // outrank the service derivation and re-split a proxied lane from its direct twin.
-    // Regenerable by design — the caller repopulates.
-    if (version !== PROXY_CATALOG_VERSION)
-        return null;
-    if (typeof fetched_at !== "string" || typeof endpoint !== "string")
-        return null;
-    if (!Array.isArray(sources))
-        return null;
-    // An unparseable stamp is a corrupt file, not an old one: no honest age can be
-    // derived from it, and aging it from a substituted default would launder it into
-    // a fresh-looking cache. Refuse it the way every other invalid field is refused.
-    const fetchedMs = Date.parse(fetched_at);
-    if (!Number.isFinite(fetchedMs))
-        return null;
-    const issues = validateSessionConfig({ sources });
-    if (issues.some((issue) => issue.severity === "error"))
-        return null;
-    const ageMs = (deps.now?.() ?? new Date()).getTime() - fetchedMs;
-    const catalog = {
-        version,
-        fetched_at,
-        endpoint,
-        sources: sources,
-        age_ms: ageMs,
-    };
-    // A stamp ahead of our clock proves nothing about freshness — it is skew or a hand
-    // edit, and believing it would pin the cache fresh for as long as the stamp says.
-    // Not fresh and not refused: stale, with the anomaly named. Mirrors the populate
-    // short-circuit, which likewise refuses to count a future stamp as young.
-    if (ageMs < 0) {
-        return {
-            ...catalog,
-            stale: true,
-            stale_reason: `populate cache is stamped ${describeAgeMs(ageMs)} in the future ("${fetched_at}") ` +
-                `relative to this machine's clock, so its age cannot be trusted — re-run the populate.`,
-        };
-    }
-    if (ageMs >= PROXY_CATALOG_MAX_READ_AGE_MS) {
-        return {
-            ...catalog,
-            stale: true,
-            stale_reason: `populate cache was fetched ${describeAgeMs(ageMs)} ago (max ${describeAgeMs(PROXY_CATALOG_MAX_READ_AGE_MS)}), ` +
-                `so its expansion may no longer match the proxy's roster — re-run the populate.`,
-        };
-    }
-    return { ...catalog, stale: false };
-}
-//# sourceMappingURL=proxyCatalog.js.map