/**
 * MCP schema freshness tracking.
 *
 * Tracks per-server schema cache freshness with TTL-based staleness detection.
 * Used by McpLifecycleManager to decide when to trigger background re-fetches.
 */
import type { SchemaFreshness, McpSchemaRecord, QuarantineReason } from './types.js';
/**
 * Tracks schema freshness for every registered MCP server.
 *
 * Lifecycle:
 *   1. `registerServer(name)`, initialised with `unknown` freshness.
 *   2. `markFresh(name)`     , called after a successful schema fetch.
 *   3. `markFailed(name, err)`, called after a failed fetch attempt.
 *   4. `markStale(name)`     , called when a server reconnects (cache invalidated).
 *   5. `getFreshness(name)`  , returns current freshness, accounting for TTL.
 *   6. `removeServer(name)`  , drops the record on permanent disconnection.
 *   7. `markQuarantined(name, reason, detail)`, places schema into quarantine;
 *      execution is blocked until `approveQuarantine` or a successful refresh.
 *   8. `approveQuarantine(name, operatorId)`, operator override: acknowledges
 *      the quarantine and temporarily unblocks execution.
 */
export declare class McpSchemaFreshnessTracker {
    private readonly records;
    private readonly ttlMs;
    private readonly quarantineThreshold;
    /**
     * @param ttlMs               - TTL in ms before a fresh record becomes stale (default 5 min)
     * @param quarantineThreshold - consecutive failures before auto-quarantine (default 3)
     */
    constructor(ttlMs?: number, quarantineThreshold?: number);
    /**
     * Register a new server with `unknown` freshness.
     * Idempotent, calling again for an already-registered server is a no-op.
     *
     * @param serverName - Server identifier
     */
    registerServer(serverName: string): void;
    /**
     * Remove a server's freshness record.
     *
     * @param serverName - Server identifier
     */
    removeServer(serverName: string): void;
    /**
     * Mark a server's schemas as freshly fetched.
     * Resets the consecutive failure counter and sets the expiry timestamp.
     *
     * @param serverName - Server identifier
     */
    markFresh(serverName: string): void;
    /**
     * Mark a schema fetch as failed.
     * Increments consecutive failure counter.
     *
     * @param serverName - Server identifier
     * @param error      - Error message from the failed attempt
     */
    markFailed(serverName: string, error: string): void;
    /**
     * Mark a server's schemas as stale (e.g. after reconnect or explicit invalidation).
     *
     * @param serverName - Server identifier
     */
    markStale(serverName: string): void;
    /**
     * Place a server's schema into quarantine.
     *
     * Quarantine blocks all tool execution on the server until the operator
     * approves an override (`approveQuarantine`) or a successful schema refresh
     * occurs (`markFresh`).
     *
     * @param serverName - Server identifier
     * @param reason     - Why quarantine is being applied
     * @param detail     - Optional human-readable detail shown in the MCP panel
     */
    markQuarantined(serverName: string, reason: QuarantineReason, detail?: string): void;
    /**
     * Operator override: acknowledge a quarantined schema and temporarily unblock
     * tool execution without refreshing the schema.
     *
     * The quarantine record is preserved (with override metadata) so auditors can
     * see that execution was approved under a quarantined schema. Freshness
     * transitions back to `stale` to signal a refresh is still needed.
     *
     * @param serverName - Server identifier
     * @param operatorId - Identifier of the operator acknowledging the override
     */
    approveQuarantine(serverName: string, operatorId: string): void;
    /**
     * Return the current freshness of a server's schema cache.
     *
     * If the stored state is `fresh` but the TTL has elapsed, returns `stale`
     * and updates the record in-place.
     *
     * @param serverName - Server identifier
     */
    getFreshness(serverName: string): SchemaFreshness;
    /**
     * Returns `true` if the server's schema is quarantined and tool execution
     * should be blocked.
     *
     * @param serverName - Server identifier
     */
    isQuarantined(serverName: string): boolean;
    /**
     * Return the full schema record for a server, or `null` if not registered.
     *
     * @param serverName - Server identifier
     */
    getRecord(serverName: string): McpSchemaRecord | null;
    private _getOrCreate;
    private _applyQuarantine;
}
//# sourceMappingURL=schema-freshness.d.ts.map