@sriinnu/kosha-discovery 0.5.0

package/dist/registry.js

@@ -0,0 +1,248 @@
+/**
+ * kosha-discovery — Thin registry façade.
+ *
+ * I keep `ModelRegistry` as the stable public API while the heavy lifting
+ * lives in focused helper modules that stay under the file-size policy.
+ * @module
+ */
+import { readFile } from "fs/promises";
+import { homedir } from "os";
+import { join } from "path";
+import { normalizeProviderId } from "./provider-catalog.js";
+import { registryBuildSnapshot, registryClassifyError, registryDiscoveryDelta, registryDiscoverySnapshot, registryMakeCursor, registryRecordDiscoveryMutation, registryRecordObservation, registrySnapshotForDelta, registryWatchDiscovery, } from "./registry-discovery.js";
+import { modelRoles, modelSupportsRole, normalizeRoleToken, registryCapabilities, registryCheapestModels, registryMissingCredentialPrompts, registryModelRouteInfo, registryModelRoutes, registryModels, registryProviderRoles, } from "./registry-query.js";
+import { registryCheapestCandidates, registryExecutionBindingHints, } from "./registry-selection.js";
+import { createRegistryState } from "./registry-state.js";
+import { enrichRegistryModels, fallbackRegistryCredential, getRegistryCredentialResolver, loadRegistryDiscoverers, loadRegistryFromCache, populateRegistryModelAliases, registryDiscover, registryRefresh, saveRegistryToCache, } from "./registry-runtime.js";
+/**
+ * Public registry API for provider discovery and routing-oriented queries.
+ */
+export class ModelRegistry {
+    state;
+    constructor(config) {
+        this.state = createRegistryState(config);
+        this.currentCursor = registryMakeCursor(this.state);
+    }
+    /** Compatibility accessor retained for existing tests and debug hooks. */
+    get providerMap() { return this.state.providerMap; }
+    /** Compatibility accessor retained for existing tests and debug hooks. */
+    get aliasResolver() { return this.state.aliasResolver; }
+    /** Compatibility accessor retained for existing tests and debug hooks. */
+    get discoveredAt() { return this.state.discoveredAt; }
+    set discoveredAt(value) { this.state.discoveredAt = value; }
+    /** Compatibility accessor retained for existing tests and debug hooks. */
+    get healthTracker() { return this.state.healthTracker; }
+    get currentCursor() { return this.state.currentCursor; }
+    set currentCursor(value) { this.state.currentCursor = value; }
+    get lastSnapshotCache() { return this.state.lastSnapshotCache; }
+    set lastSnapshotCache(value) { this.state.lastSnapshotCache = value; }
+    /**
+     * Run discovery across all or selected providers.
+     */
+    async discover(options) {
+        const credentialResolver = await getRegistryCredentialResolver();
+        return registryDiscover(this.state, this.dependencies(credentialResolver), options);
+    }
+    /**
+     * Force a fresh discovery pass, bypassing cache for the targeted scope.
+     */
+    async refresh(providerId) {
+        await registryRefresh(this.state, (options) => this.discover(options), providerId);
+    }
+    /**
+     * Force a live discovery fetch and return a summary payload.
+     *
+     * This always bypasses cache, so callers can ask for "latest now"
+     * without relying on TTL expiry.
+     */
+    async fetchLatestDetails(options) {
+        const providers = await this.discover({ ...options, force: true });
+        return {
+            providers,
+            modelCount: providers.reduce((sum, provider) => sum + provider.models.length, 0),
+            discoveredAt: this.discoveredAt,
+        };
+    }
+    /** Return all known models with optional provider/origin/mode filters. */
+    models(filter) {
+        return registryModels(this.state, filter);
+    }
+    /** Return the provider -> model -> roles matrix used by routing clients. */
+    providerRoles(filter) {
+        return registryProviderRoles(this.state, filter);
+    }
+    /** Return prompts for discovered providers missing required credentials. */
+    missingCredentialPrompts(providerIds) {
+        return registryMissingCredentialPrompts(this.state, providerIds);
+    }
+    /** Return the cheapest ranked legacy candidates for the requested query. */
+    cheapestModels(options) {
+        return registryCheapestModels(this.state, options);
+    }
+    /** Return every provider route for a normalized model identifier. */
+    modelRoutes(modelId) {
+        return registryModelRoutes(this.state, modelId);
+    }
+    /** Return enriched route metadata for a normalized model identifier. */
+    modelRouteInfo(modelId) {
+        return registryModelRouteInfo(this.state, modelId);
+    }
+    /** Resolve a model by canonical ID or configured alias. */
+    model(idOrAlias) {
+        const resolvedId = this.aliasResolver.resolve(idOrAlias);
+        return registryModels(this.state).find((model) => model.id === resolvedId);
+    }
+    /** Return a single provider by canonical or alias provider ID. */
+    provider(id) {
+        const normalizedProviderId = normalizeProviderId(id) ?? id;
+        return this.providerMap.get(normalizedProviderId);
+    }
+    /** Return all currently known providers. */
+    providers_list() {
+        return Array.from(this.providerMap.values());
+    }
+    /** Return errors captured during the most recent discovery pass. */
+    discoveryErrors() {
+        return [...this.state.lastDiscoveryErrors];
+    }
+    /** Return raw circuit-breaker health details for monitoring/debugging. */
+    providerHealth() {
+        return this.healthTracker.healthReport();
+    }
+    /** Build the stable v1 discovery snapshot for daemon consumers. */
+    discoverySnapshot() {
+        return registryDiscoverySnapshot(this.state);
+    }
+    /** Return delta batches since the provided cursor. */
+    discoveryDelta(options) {
+        return registryDiscoveryDelta(this.state, options);
+    }
+    /** Stream live discovery deltas through an async iterator. */
+    watchDiscovery(options) {
+        return registryWatchDiscovery(this.state, options);
+    }
+    /** Return cheapest candidates using the trusted v1 capability taxonomy. */
+    cheapestCandidates(query = {}) {
+        return registryCheapestCandidates(this.state, query);
+    }
+    /** Return query-scoped binding hints without taking routing authority. */
+    executionBindingHints(query = {}) {
+        return registryExecutionBindingHints(this.state, query);
+    }
+    /** Reset one provider breaker or the full health tracker. */
+    resetHealth(providerId) {
+        if (providerId) {
+            this.healthTracker.breaker(normalizeProviderId(providerId) ?? providerId).reset();
+            return;
+        }
+        this.healthTracker.resetAll();
+    }
+    /** Aggregate capability statistics across the current model set. */
+    capabilities(filter) {
+        return registryCapabilities(this.state, filter);
+    }
+    /** Normalize a role or capability token used by legacy queries. */
+    normalizeRoleToken(value) {
+        return normalizeRoleToken(value);
+    }
+    /** Return the deduplicated role list for a model. */
+    modelRoles(model) {
+        return modelRoles(model);
+    }
+    /** Check whether a model satisfies a role or capability query. */
+    modelSupportsRole(model, roleOrCapability) {
+        return modelSupportsRole(model, roleOrCapability);
+    }
+    /** Resolve a configured alias to its canonical model ID. */
+    resolve(alias) {
+        return this.aliasResolver.resolve(alias);
+    }
+    /** Add a custom alias mapping. */
+    alias(short, modelId) {
+        this.aliasResolver.addAlias(short, modelId);
+    }
+    /** Serialize the registry into a plain JSON-compatible snapshot. */
+    toJSON() {
+        return {
+            providers: this.providers_list(),
+            aliases: this.aliasResolver.all(),
+            discoveredAt: this.discoveredAt,
+        };
+    }
+    /** Restore a registry instance from a serialized JSON payload. */
+    static fromJSON(data) {
+        const registry = new ModelRegistry({ aliases: data.aliases });
+        for (const provider of data.providers) {
+            registry.providerMap.set(provider.id, provider);
+        }
+        registry.discoveredAt = data.discoveredAt;
+        registry.currentCursor = registryMakeCursor(registry.state);
+        registry.lastSnapshotCache = registryBuildSnapshot(registry.state, registry.currentCursor);
+        return registry;
+    }
+    /** Load config from global/project files and merge explicit overrides last. */
+    static async loadConfigFile(overrides) {
+        const layers = [];
+        const globalConfig = await ModelRegistry.readJsonFile(join(homedir(), ".kosharc.json"));
+        const projectConfig = await ModelRegistry.readJsonFile(join(process.cwd(), "kosha.config.json"));
+        if (globalConfig)
+            layers.push(globalConfig);
+        if (projectConfig)
+            layers.push(projectConfig);
+        if (overrides)
+            layers.push(overrides);
+        if (layers.length === 0)
+            return {};
+        // I only deep-merge the provider and alias maps; the rest stays shallow.
+        return layers.reduce((merged, layer) => ({
+            ...merged,
+            ...layer,
+            providers: { ...merged.providers, ...layer.providers },
+            aliases: { ...merged.aliases, ...layer.aliases },
+        }), {});
+    }
+    dependencies(credentialResolver) {
+        return {
+            // I bind the loaded resolver once per discovery pass to avoid repeated dynamic imports.
+            resolveCredential: credentialResolver ? (providerId, explicitKey) => credentialResolver.resolve(providerId, explicitKey) : null,
+            loadDiscoverers: (providerIds, includeLocal) => loadRegistryDiscoverers(this.state, providerIds, includeLocal),
+            enrichModels: () => enrichRegistryModels(this.state),
+            populateModelAliases: () => populateRegistryModelAliases(this.state),
+            loadFromCache: (providerIds) => loadRegistryFromCache(this.state, providerIds),
+            saveToCache: () => saveRegistryToCache(this.state),
+            fallbackCredential: fallbackRegistryCredential,
+            snapshotForDelta: () => registrySnapshotForDelta(this.state),
+            recordDiscoveryMutation: (previousSnapshot) => registryRecordDiscoveryMutation(this.state, previousSnapshot),
+            recordObservation: (providerId, entry) => registryRecordObservation(this.state, providerId, entry),
+            classifyError: (errorMessage) => registryClassifyError(errorMessage),
+        };
+    }
+    /** Compatibility wrapper retained for tests that probe internal mutation APIs. */
+    snapshotForDelta() {
+        return registrySnapshotForDelta(this.state);
+    }
+    /** Compatibility wrapper retained for tests that probe internal mutation APIs. */
+    recordDiscoveryMutation(previousSnapshot) {
+        return registryRecordDiscoveryMutation(this.state, previousSnapshot);
+    }
+    /** Compatibility wrapper retained for tests that probe internal mutation APIs. */
+    recordObservation(providerId, entry) {
+        return registryRecordObservation(this.state, providerId, entry);
+    }
+    /** Compatibility wrapper retained for internal error classification hooks. */
+    classifyError(errorMessage) {
+        return registryClassifyError(errorMessage);
+    }
+    static async readJsonFile(filePath) {
+        try {
+            return JSON.parse(await readFile(filePath, "utf-8"));
+        }
+        catch (error) {
+            if (error instanceof SyntaxError) {
+                console.warn(`kosha: config file has invalid JSON: ${filePath}`);
+            }
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAC7B,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EACN,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,EACtB,yBAAyB,EACzB,kBAAkB,EAClB,+BAA+B,EAC/B,yBAAyB,EACzB,wBAAwB,EACxB,sBAAsB,GACtB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACN,UAAU,EACV,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,sBAAsB,EACtB,gCAAgC,EAChC,sBAAsB,EACtB,mBAAmB,EACnB,cAAc,EACd,qBAAqB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACN,0BAA0B,EAC1B,6BAA6B,GAC7B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE1D,OAAO,EACN,oBAAoB,EACpB,0BAA0B,EAC1B,6BAA6B,EAC7B,uBAAuB,EACvB,qBAAqB,EACrB,4BAA4B,EAC5B,gBAAgB,EAChB,eAAe,EACf,mBAAmB,GACnB,MAAM,uBAAuB,CAAC;AA4B/B;;GAEG;AACH,MAAM,OAAO,aAAa;IACR,KAAK,CAAgB;IAEtC,YAAY,MAAoB;QAC/B,IAAI,CAAC,KAAK,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC;QACzC,IAAI,CAAC,aAAa,GAAG,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACrD,CAAC;IAED,0EAA0E;IAC1E,IAAY,WAAW,KAAgC,OAAO,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC;IACvF,0EAA0E;IAC1E,IAAY,aAAa,KAAK,OAAO,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC;IAChE,0EAA0E;IAC1E,IAAY,YAAY,KAAa,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC;IACtE,IAAY,YAAY,CAAC,KAAa,IAAI,IAAI,CAAC,KAAK,CAAC,YAAY,GAAG,KAAK,CAAC,CAAC,CAAC;IAC5E,0EAA0E;IAC1E,IAAY,aAAa,KAAK,OAAO,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC;IAChE,IAAY,aAAa,KAAa,OAAO,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC;IACxE,IAAY,aAAa,CAAC,KAAa,IAAI,IAAI,CAAC,KAAK,CAAC,aAAa,GAAG,KAAK,CAAC,CAAC,CAAC;IAC9E,IAAY,iBAAiB,KAAiC,OAAO,IAAI,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC,CAAC;IACpG,IAAY,iBAAiB,CAAC,KAAiC,IAAI,IAAI,CAAC,KAAK,CAAC,iBAAiB,GAAG,KAAK,CAAC,CAAC,CAAC;IAE1G;;OAEG;IACH,KAAK,CAAC,QAAQ,CAAC,OAA0B;QACxC,MAAM,kBAAkB,GAAG,MAAM,6BAA6B,EAAE,CAAC;QACjE,OAAO,gBAAgB,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,YAAY,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC,CAAC;IACrF,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAO,CAAC,UAAmB;QAChC,MAAM,eAAe,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC,CAAC;IACpF,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,kBAAkB,CAAC,OAAgC;QACxD,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,EAAE,GAAG,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACnE,OAAO;YACN,SAAS;YACT,UAAU,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,QAAQ,EAAE,EAAE,CAAC,GAAG,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;YAChF,YAAY,EAAE,IAAI,CAAC,YAAY;SAC/B,CAAC;IACH,CAAC;IAED,0EAA0E;IAC1E,MAAM,CAAC,MAA8F;QACpG,OAAO,cAAc,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAC3C,CAAC;IAED,4EAA4E;IAC5E,aAAa,CAAC,MAAyB;QACtC,OAAO,qBAAqB,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAClD,CAAC;IAED,4EAA4E;IAC5E,wBAAwB,CAAC,WAAsB;QAC9C,OAAO,gCAAgC,CAAC,IAAI,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;IAClE,CAAC;IAED,4EAA4E;IAC5E,cAAc,CAAC,OAA8B;QAC5C,OAAO,sBAAsB,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACpD,CAAC;IAED,qEAAqE;IACrE,WAAW,CAAC,OAAe;QAC1B,OAAO,mBAAmB,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACjD,CAAC;IAED,wEAAwE;IACxE,cAAc,CAAC,OAAe;QAC7B,OAAO,sBAAsB,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACpD,CAAC;IAED,2DAA2D;IAC3D,KAAK,CAAC,SAAiB;QACtB,MAAM,UAAU,GAAG,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACzD,OAAO,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,UAAU,CAAC,CAAC;IAC5E,CAAC;IAED,kEAAkE;IAClE,QAAQ,CAAC,EAAU;QAClB,MAAM,oBAAoB,GAAG,mBAAmB,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC;QAC3D,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;IACnD,CAAC;IAED,4CAA4C;IAC5C,cAAc;QACb,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC;IAC9C,CAAC;IAED,oEAAoE;IACpE,eAAe;QACd,OAAO,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC;IAC5C,CAAC;IAED,0EAA0E;IAC1E,cAAc;QACb,OAAO,IAAI,CAAC,aAAa,CAAC,YAAY,EAAE,CAAC;IAC1C,CAAC;IAED,mEAAmE;IACnE,iBAAiB;QAChB,OAAO,yBAAyB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC9C,CAAC;IAED,sDAAsD;IACtD,cAAc,CAAC,OAAyC;QACvD,OAAO,sBAAsB,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACpD,CAAC;IAED,8DAA8D;IAC9D,cAAc,CAAC,OAAyC;QACvD,OAAO,sBAAsB,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACpD,CAAC;IAED,2EAA2E;IAC3E,kBAAkB,CAAC,QAA+B,EAAE;QACnD,OAAO,0BAA0B,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACtD,CAAC;IAED,0EAA0E;IAC1E,qBAAqB,CAAC,QAA+B,EAAE;QACtD,OAAO,6BAA6B,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACzD,CAAC;IAED,6DAA6D;IAC7D,WAAW,CAAC,UAAmB;QAC9B,IAAI,UAAU,EAAE,CAAC;YAChB,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,mBAAmB,CAAC,UAAU,CAAC,IAAI,UAAU,CAAC,CAAC,KAAK,EAAE,CAAC;YAClF,OAAO;QACR,CAAC;QACD,IAAI,CAAC,aAAa,CAAC,QAAQ,EAAE,CAAC;IAC/B,CAAC;IAED,oEAAoE;IACpE,YAAY,CAAC,MAA8B;QAC1C,OAAO,oBAAoB,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACjD,CAAC;IAED,mEAAmE;IACnE,kBAAkB,CAAC,KAAa;QAC/B,OAAO,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAClC,CAAC;IAED,qDAAqD;IACrD,UAAU,CAAC,KAAgB;QAC1B,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IAED,kEAAkE;IAClE,iBAAiB,CAAC,KAAgB,EAAE,gBAAwB;QAC3D,OAAO,iBAAiB,CAAC,KAAK,EAAE,gBAAgB,CAAC,CAAC;IACnD,CAAC;IAED,4DAA4D;IAC5D,OAAO,CAAC,KAAa;QACpB,OAAO,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC1C,CAAC;IAED,kCAAkC;IAClC,KAAK,CAAC,KAAa,EAAE,OAAe;QACnC,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAC7C,CAAC;IAED,oEAAoE;IACpE,MAAM;QACL,OAAO;YACN,SAAS,EAAE,IAAI,CAAC,cAAc,EAAE;YAChC,OAAO,EAAE,IAAI,CAAC,aAAa,CAAC,GAAG,EAAE;YACjC,YAAY,EAAE,IAAI,CAAC,YAAY;SAC/B,CAAC;IACH,CAAC;IAED,kEAAkE;IAClE,MAAM,CAAC,QAAQ,CAAC,IAA0F;QACzG,MAAM,QAAQ,GAAG,IAAI,aAAa,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;QAC9D,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACvC,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;QACjD,CAAC;QACD,QAAQ,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;QAC1C,QAAQ,CAAC,aAAa,GAAG,kBAAkB,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC5D,QAAQ,CAAC,iBAAiB,GAAG,qBAAqB,CAAC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,aAAa,CAAC,CAAC;QAC3F,OAAO,QAAQ,CAAC;IACjB,CAAC;IAED,+EAA+E;IAC/E,MAAM,CAAC,KAAK,CAAC,cAAc,CAAC,SAAuB;QAClD,MAAM,MAAM,GAAkB,EAAE,CAAC;QACjC,MAAM,YAAY,GAAG,MAAM,aAAa,CAAC,YAAY,CAAc,IAAI,CAAC,OAAO,EAAE,EAAE,eAAe,CAAC,CAAC,CAAC;QACrG,MAAM,aAAa,GAAG,MAAM,aAAa,CAAC,YAAY,CAAc,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,mBAAmB,CAAC,CAAC,CAAC;QAE9G,IAAI,YAAY;YAAE,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAC5C,IAAI,aAAa;YAAE,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAC9C,IAAI,SAAS;YAAE,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACtC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QAEnC,yEAAyE;QACzE,OAAO,MAAM,CAAC,MAAM,CAAc,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;YACrD,GAAG,MAAM;YACT,GAAG,KAAK;YACR,SAAS,EAAE,EAAE,GAAG,MAAM,CAAC,SAAS,EAAE,GAAG,KAAK,CAAC,SAAS,EAAE;YACtD,OAAO,EAAE,EAAE,GAAG,MAAM,CAAC,OAAO,EAAE,GAAG,KAAK,CAAC,OAAO,EAAE;SAChD,CAAC,EAAE,EAAE,CAAC,CAAC;IACT,CAAC;IAEO,YAAY,CACnB,kBAA+G;QAE/G,OAAO;YACN,wFAAwF;YACxF,iBAAiB,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,WAAW,EAAE,EAAE,CAAC,kBAAkB,CAAC,OAAO,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI;YAC/H,eAAe,EAAE,CAAC,WAAW,EAAE,YAAY,EAAE,EAAE,CAAC,uBAAuB,CAAC,IAAI,CAAC,KAAK,EAAE,WAAW,EAAE,YAAY,CAAC;YAC9G,YAAY,EAAE,GAAG,EAAE,CAAC,oBAAoB,CAAC,IAAI,CAAC,KAAK,CAAC;YACpD,oBAAoB,EAAE,GAAG,EAAE,CAAC,4BAA4B,CAAC,IAAI,CAAC,KAAK,CAAC;YACpE,aAAa,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,qBAAqB,CAAC,IAAI,CAAC,KAAK,EAAE,WAAW,CAAC;YAC9E,WAAW,EAAE,GAAG,EAAE,CAAC,mBAAmB,CAAC,IAAI,CAAC,KAAK,CAAC;YAClD,kBAAkB,EAAE,0BAA0B;YAC9C,gBAAgB,EAAE,GAAG,EAAE,CAAC,wBAAwB,CAAC,IAAI,CAAC,KAAK,CAAC;YAC5D,uBAAuB,EAAE,CAAC,gBAAgB,EAAE,EAAE,CAAC,+BAA+B,CAAC,IAAI,CAAC,KAAK,EAAE,gBAAgB,CAAC;YAC5G,iBAAiB,EAAE,CAAC,UAAU,EAAE,KAAK,EAAE,EAAE,CAAC,yBAAyB,CAAC,IAAI,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,CAAC;YAClG,aAAa,EAAE,CAAC,YAAY,EAAE,EAAE,CAAC,qBAAqB,CAAC,YAAY,CAAC;SACpE,CAAC;IACH,CAAC;IAED,kFAAkF;IAC1E,gBAAgB;QACvB,OAAO,wBAAwB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC7C,CAAC;IAED,kFAAkF;IAC1E,uBAAuB,CAAC,gBAA4C;QAC3E,OAAO,+BAA+B,CAAC,IAAI,CAAC,KAAK,EAAE,gBAAgB,CAAC,CAAC;IACtE,CAAC;IAED,kFAAkF;IAC1E,iBAAiB,CACxB,UAAkB,EAClB,KAA6E;QAE7E,OAAO,yBAAyB,CAAC,IAAI,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC;IACjE,CAAC;IAED,8EAA8E;IACtE,aAAa,CAAC,YAAoB;QACzC,OAAO,qBAAqB,CAAC,YAAY,CAAC,CAAC;IAC5C,CAAC;IAEO,MAAM,CAAC,KAAK,CAAC,YAAY,CAAI,QAAgB;QACpD,IAAI,CAAC;YACJ,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAM,CAAC;QAC3D,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACzB,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;gBAClC,OAAO,CAAC,IAAI,CAAC,wCAAwC,QAAQ,EAAE,CAAC,CAAC;YAClE,CAAC;YACD,OAAO,IAAI,CAAC;QACb,CAAC;IACF,CAAC;CACD"}

package/dist/resilience.d.ts

@@ -0,0 +1,212 @@
+/**
+ * kosha-discovery — Resilience primitives.
+ *
+ * Provides a {@link CircuitBreaker} for per-provider fault isolation,
+ * a {@link HealthTracker} that manages breakers for all known providers,
+ * and a {@link StaleCachePolicy} that implements stale-while-revalidate
+ * semantics on top of {@link KoshaCache}.
+ *
+ * The module is self-contained with no side-effects on import.
+ * @module
+ */
+import type { KoshaCache } from "./cache.js";
+/** Possible states of a {@link CircuitBreaker}. */
+export type CircuitState = "closed" | "open" | "half-open";
+/** Configuration options for a {@link CircuitBreaker} instance. */
+export interface CircuitBreakerOptions {
+    /**
+     * Number of consecutive failures before the circuit opens.
+     * @default 3
+     */
+    failureThreshold?: number;
+    /**
+     * Time (in milliseconds) the circuit stays open before transitioning
+     * to `half-open` to allow a probe request.
+     * @default 60_000
+     */
+    resetTimeoutMs?: number;
+    /**
+     * Number of consecutive successes in `half-open` state required to
+     * close the circuit again.
+     * @default 1
+     */
+    halfOpenSuccessThreshold?: number;
+}
+/**
+ * A point-in-time health snapshot for a single provider circuit.
+ */
+export interface ProviderHealth {
+    /** Provider slug this health record belongs to. */
+    providerId: string;
+    /** Current circuit state. */
+    state: CircuitState;
+    /** Number of consecutive failures recorded since last reset. */
+    failureCount: number;
+    /** Unix timestamp (ms) of the most recent recorded failure, or 0. */
+    lastFailureTime: number;
+    /** Error message from the most recent failure, if available. */
+    lastError?: string;
+    /** Unix timestamp (ms) of the most recent recorded success, or 0. */
+    lastSuccessTime: number;
+}
+/**
+ * Wrapper returned by {@link StaleCachePolicy.getWithStale}.
+ */
+export interface StaleResult<T> {
+    /** The cached payload. */
+    data: T;
+    /** True when the cache entry has exceeded its TTL. */
+    stale: boolean;
+    /** Milliseconds elapsed since the entry was written. */
+    age: number;
+    /** Unix timestamp (ms) when the entry was originally cached. */
+    cachedAt: number;
+}
+/**
+ * Per-provider circuit breaker with three states.
+ *
+ * - **closed** — Normal operation. All requests are allowed. Consecutive
+ *   failures are counted; once the {@link CircuitBreakerOptions.failureThreshold}
+ *   is reached the circuit transitions to `open`.
+ * - **open** — Requests are rejected immediately (canExecute returns false).
+ *   After {@link CircuitBreakerOptions.resetTimeoutMs} has elapsed the circuit
+ *   transitions to `half-open` so a single probe request can be attempted.
+ * - **half-open** — Exactly one request is let through. A success closes the
+ *   circuit; a failure re-opens it and resets the timeout.
+ *
+ * @example
+ * const cb = new CircuitBreaker("anthropic", { failureThreshold: 5 });
+ * if (cb.canExecute()) {
+ *   try {
+ *     const result = await callApi();
+ *     cb.onSuccess();
+ *   } catch (err) {
+ *     cb.onFailure(err.message);
+ *   }
+ * }
+ */
+export declare class CircuitBreaker {
+    readonly providerId: string;
+    private options;
+    private state;
+    private failureCount;
+    private successCount;
+    private lastFailureTime;
+    private lastSuccessTime;
+    private lastError?;
+    /** Resolved threshold: consecutive failures before opening. */
+    private readonly failureThreshold;
+    /** Resolved open-state duration before allowing a probe. */
+    private readonly resetTimeoutMs;
+    /** Resolved success count in half-open needed to close. */
+    private readonly halfOpenSuccessThreshold;
+    constructor(providerId: string, options?: CircuitBreakerOptions);
+    /**
+     * Check whether a request should be allowed through.
+     *
+     * - `closed` → always true.
+     * - `open` → false, unless the reset timeout has elapsed, in which case
+     *   the circuit transitions to `half-open` and returns true for the probe.
+     * - `half-open` → true (the probe request is already in flight).
+     */
+    canExecute(): boolean;
+    /**
+     * Record a successful API call.
+     *
+     * In `half-open` state, once enough successes accumulate (per
+     * {@link CircuitBreakerOptions.halfOpenSuccessThreshold}) the circuit closes.
+     * In `closed` state the failure counter is reset.
+     */
+    onSuccess(): void;
+    /**
+     * Record a failed API call.
+     *
+     * In `closed` state, increments the failure counter and opens the circuit
+     * when the threshold is reached. In `half-open` state, immediately
+     * re-opens the circuit.
+     *
+     * @param error - Optional error message to store for diagnostics.
+     */
+    onFailure(error?: string): void;
+    /**
+     * Return a point-in-time health snapshot for this provider's circuit.
+     */
+    health(): ProviderHealth;
+    /**
+     * Force the circuit back to `closed` state, resetting all counters.
+     * Useful for manual recovery or test teardown.
+     */
+    reset(): void;
+    private transitionToOpen;
+    private transitionToClosed;
+}
+/**
+ * Manages {@link CircuitBreaker} instances for all tracked providers.
+ *
+ * Breakers are created lazily on first access via {@link breaker}.
+ *
+ * @example
+ * const tracker = new HealthTracker();
+ * const cb = tracker.breaker("anthropic");
+ * if (cb.canExecute()) { ... }
+ */
+export declare class HealthTracker {
+    private breakers;
+    /**
+     * Retrieve the {@link CircuitBreaker} for the given provider, creating
+     * one with default options if it does not yet exist.
+     *
+     * @param providerId - Provider slug (e.g. `"anthropic"`).
+     * @param options    - Options forwarded to a newly created breaker only.
+     */
+    breaker(providerId: string, options?: CircuitBreakerOptions): CircuitBreaker;
+    /**
+     * Return health snapshots for every tracked provider, sorted by provider ID.
+     */
+    healthReport(): ProviderHealth[];
+    /**
+     * Return provider IDs whose circuit is `closed` or `half-open`
+     * (i.e. requests are currently being allowed through).
+     */
+    availableProviders(): string[];
+    /**
+     * Return provider IDs whose circuit is `open`
+     * (i.e. requests are currently being rejected).
+     */
+    downProviders(): string[];
+    /**
+     * Reset all tracked circuit breakers to `closed` state.
+     */
+    resetAll(): void;
+}
+/**
+ * Utility that wraps {@link KoshaCache} reads to implement
+ * stale-while-revalidate semantics.
+ *
+ * Unlike the registry's normal cache path (which returns `null` for expired
+ * entries), this policy always returns whatever was cached along with a
+ * `stale` flag. This lets callers serve the old data immediately while
+ * triggering a background refresh.
+ *
+ * Returns `null` only when the cache has never held a value for the key.
+ *
+ * @example
+ * const result = await StaleCachePolicy.getWithStale<ModelCard[]>(cache, "provider_anthropic");
+ * if (result) {
+ *   serveToClient(result.data); // always fast
+ *   if (result.stale) triggerBackgroundRefresh();
+ * }
+ */
+export declare class StaleCachePolicy {
+    /**
+     * Fetch a cached value regardless of its expiry, annotating the result
+     * with staleness metadata.
+     *
+     * @param cache - The {@link KoshaCache} instance to read from.
+     * @param key   - Cache key to look up.
+     * @returns A {@link StaleResult} when any cached value exists, or `null`
+     *          when the key has never been written.
+     */
+    static getWithStale<T>(cache: KoshaCache, key: string): Promise<StaleResult<T> | null>;
+}
+//# sourceMappingURL=resilience.d.ts.map

package/dist/resilience.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resilience.d.ts","sourceRoot":"","sources":["../src/resilience.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAM7C,mDAAmD;AACnD,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3D,mEAAmE;AACnE,MAAM,WAAW,qBAAqB;IACrC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,wBAAwB,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,KAAK,EAAE,YAAY,CAAC;IACpB,gEAAgE;IAChE,YAAY,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,eAAe,EAAE,MAAM,CAAC;IACxB,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,eAAe,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC7B,0BAA0B;IAC1B,IAAI,EAAE,CAAC,CAAC;IACR,sDAAsD;IACtD,KAAK,EAAE,OAAO,CAAC;IACf,wDAAwD;IACxD,GAAG,EAAE,MAAM,CAAC;IACZ,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;CACjB;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,cAAc;IAed,QAAQ,CAAC,UAAU,EAAE,MAAM;IAAE,OAAO,CAAC,OAAO;IAdxD,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,SAAS,CAAC,CAAS;IAE3B,+DAA+D;IAC/D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,4DAA4D;IAC5D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,2DAA2D;IAC3D,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAS;gBAE7B,UAAU,EAAE,MAAM,EAAU,OAAO,GAAE,qBAA0B;IAMpF;;;;;;;OAOG;IACH,UAAU,IAAI,OAAO;IAoBrB;;;;;;OAMG;IACH,SAAS,IAAI,IAAI;IAiBjB;;;;;;;;OAQG;IACH,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAkB/B;;OAEG;IACH,MAAM,IAAI,cAAc;IAWxB;;;OAGG;IACH,KAAK,IAAI,IAAI;IAWb,OAAO,CAAC,gBAAgB;IAKxB,OAAO,CAAC,kBAAkB;CAK1B;AAMD;;;;;;;;;GASG;AACH,qBAAa,aAAa;IACzB,OAAO,CAAC,QAAQ,CAAqC;IAErD;;;;;;OAMG;IACH,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,cAAc;IAS5E;;OAEG;IACH,YAAY,IAAI,cAAc,EAAE;IAMhC;;;OAGG;IACH,kBAAkB,IAAI,MAAM,EAAE;IAO9B;;;OAGG;IACH,aAAa,IAAI,MAAM,EAAE;IAOzB;;OAEG;IACH,QAAQ,IAAI,IAAI;CAKhB;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,gBAAgB;IAC5B;;;;;;;;OAQG;WACU,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;CA8B5F"}