audit-tools 0.34.41 → 0.35.0

package/dist/shared/providers/proxyCatalog.d.ts

@@ -1,158 +0,0 @@
-import type { DispatchableSource } from "../types/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 declare const PROXY_CATALOG_FILENAME = "catalog-cache.json";
-/** Top-K models expanded per backend provider when the operator declares no `top_k`. */
-export declare const DEFAULT_PROXY_TOP_K = 3;
-/** Timeout (ms) for populate-time model verification probes. */
-export declare const POPULATE_PROBE_TIMEOUT_MS = 3000;
-/** Concurrency limit for populate-time model verification probes. */
-export declare 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 declare const POPULATE_CACHE_FRESH_TTL_MS: number;
-/**
- * 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 declare const PROXY_CATALOG_MAX_READ_AGE_MS: number;
-/** Resolve the populate-cache path for this machine (state dir via `io/stateDir.ts`). */
-export declare function resolveProxyCatalogPath(homeDir?: string): string;
-/**
- * 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 declare const PROXY_CATALOG_VERSION = 2;
-/** The on-disk cache shape: the expansion + when it was fetched. */
-export interface ProxyCatalog {
-    /** Shape version — see {@link PROXY_CATALOG_VERSION}. Absent ⇒ pre-versioned (v1). */
-    version: number;
-    /**
-     * ISO timestamp of the populate fetch. REQUIRED to be parseable — the read-side
-     * age rule is derived from it, and an age derived from a substituted default
-     * would launder a corrupt file into a fresh-looking one.
-     */
-    fetched_at: string;
-    /** The proxy endpoint the registry was fetched from. */
-    endpoint: string;
-    /** Expanded `claude-worker` sources, ready to fold into the dispatch pool. */
-    sources: DispatchableSource[];
-}
-/**
- * The cache as READ: the persisted shape plus the read-time age verdict.
- *
- * Staleness is DERIVED at read, never persisted — a stored flag would age into a lie
- * the moment the clock moved past it. A stale cache is returned, not withheld: the
- * expansion is the caller's to keep (dropping it would surface as "cache absent, run
- * the populate", which sends the operator after a file that is right there), and it is
- * not thrown either (the resolve path must not be failable by an old file).
- *
- * `stale_reason` rides the `stale: true` branch so it cannot be read without branching
- * on the verdict, and so every caller reports one wording instead of composing its own.
- */
-export type ProxyCatalogRead = ProxyCatalog & {
-    /** Cache age at read time, ms. Negative ⇒ stamped ahead of this machine's clock. */
-    age_ms: number;
-} & ({
-    stale: false;
-    stale_reason?: undefined;
-} | {
-    stale: true;
-    stale_reason: string;
-});
-export interface PopulateProxyCatalogOptions {
-    /** The proxy base url (`GET <endpoint>/v1/models`, `GET <endpoint>/model/info`). */
-    endpoint: string;
-    /** Models expanded per backend provider (declared `proxy.top_k`); default {@link DEFAULT_PROXY_TOP_K}. */
-    topK?: number;
-    /**
-     * Operator-declared blended $/Mtok for the proxied lane (`proxy.cost_per_mtok`,
-     * the free-to-operator axis). WINS over any advert price.
-     */
-    costPerMtok?: number;
-    /** Env var holding the proxy's master key when authentication is required. */
-    apiKeyEnv?: string;
-    /** Injectable fetch (tests); defaults to global fetch. */
-    fetchImpl?: typeof fetch;
-    /** Home dir override for the cache path (tests). */
-    homeDir?: string;
-    /** Clock (tests); defaults to `Date.now`-based ISO. */
-    now?: () => Date;
-}
-export interface PopulateProxyCatalogResult {
-    /** The expanded sources (also what was written when `written` is true). */
-    sources: DispatchableSource[];
-    /** Whether the cache file was (re)written. False only when the fetch itself failed. */
-    written: boolean;
-    /** Operator-facing explanation when the registry could not be fetched/parsed. */
-    reason?: string;
-    /** Models dropped during probe verification, with reasons. */
-    dropped: Array<{
-        id: string;
-        reason: string;
-    }>;
-}
-/**
- * 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 declare function populateProxyCatalog(options: PopulateProxyCatalogOptions): Promise<PopulateProxyCatalogResult>;
-export interface ReadProxyCatalogDeps {
-    /** Home dir override for the cache path (tests). */
-    homeDir?: string;
-    /** Raw cache reader (tests inject); defaults to reading the cache file. */
-    readCatalogFile?: (path: string) => string | null;
-    /** Clock (tests); defaults to `new Date()`. Fixes the age rule's reference point. */
-    now?: () => Date;
-}
-/**
- * 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 declare function readProxyCatalog(deps?: ReadProxyCatalogDeps): ProxyCatalogRead | null;
-//# sourceMappingURL=proxyCatalog.d.ts.map

package/dist/shared/providers/proxyCatalog.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"proxyCatalog.d.ts","sourceRoot":"","sources":["../../../src/shared/providers/proxyCatalog.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAGpE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,sBAAsB,uBAAuB,CAAC;AAE3D,wFAAwF;AACxF,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAUrC,gEAAgE;AAChE,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAE9C,qEAAqE;AACrE,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAE5C;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,QAAc,CAAC;AAEvD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,6BAA6B,QAAmB,CAAC;AAE9D,yFAAyF;AACzF,wBAAgB,uBAAuB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC,oEAAoE;AACpE,MAAM,WAAW,YAAY;IAC3B,sFAAsF;IACtF,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,OAAO,EAAE,kBAAkB,EAAE,CAAC;CAC/B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,gBAAgB,GAAG,YAAY,GAAG;IAC5C,oFAAoF;IACpF,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,CACE;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,YAAY,CAAC,EAAE,SAAS,CAAA;CAAE,GAC1C;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CACxC,CAAC;AA8BJ,MAAM,WAAW,2BAA2B;IAC1C,oFAAoF;IACpF,QAAQ,EAAE,MAAM,CAAC;IACjB,0GAA0G;IAC1G,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,0BAA0B;IACzC,2EAA2E;IAC3E,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,uFAAuF;IACvF,OAAO,EAAE,OAAO,CAAC;IACjB,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,OAAO,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD;AA8XD;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,0BAA0B,CAAC,CAsKrC;AAED,MAAM,WAAW,oBAAoB;IACnC,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IAClD,qFAAqF;IACrF,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAkBD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,GAAE,oBAAyB,GAC9B,gBAAgB,GAAG,IAAI,CA2DzB"}