/**
 * circuit-breaker-preflight.ts
 *
 * ASI-08 Cascading Failures — wires CircuitBreaker into the PreToolUse
 * enforcement path by default.
 *
 * BEFORE this module existed, CircuitBreaker.allowExecution() was opt-in:
 * callers had to explicitly instantiate a breaker and call allowExecution()
 * themselves (the only caller was ClaudeCodeAdapter in llm-adapters/claude.ts).
 * This was an audit finding: the proxy's evaluatePreFlight() path had no
 * circuit-breaker check, so an OPEN breaker was silently bypassed on every
 * proxy-routed tool call.
 *
 * This module provides evaluatePreFlightWithBreaker() — a drop-in wrapper
 * around the proxy evaluatorFn that:
 *   1. Checks the per-agent CircuitBreaker BEFORE dispatching the evaluatorFn.
 *   2. Returns a structured DENY verdict (PackVerdictResult) when the breaker
 *      is OPEN — does NOT throw, does NOT call the evaluatorFn.
 *   3. Emits an audit event (OWASP-tagged ASI-08) through the optional
 *      onAuditEvent callback so the event surfaces in the audit chain.
 *   4. Fails ADVISORY (ALLOW) if the breaker state store itself is unavailable
 *      / throws — per Locked Invariant 3 (graceful degradation, no throw on
 *      infra error). An advisory audit event is still emitted so operators can
 *      see the degradation.
 *   5. Short-circuits gracefully when no circuitBreaker is provided (config
 *      opt-in not set), falling through to the evaluatorFn unchanged.
 *
 * Invariants honoured:
 *   - Invariant 2 (advisory, never authoritative): a genuine OPEN state DOES
 *     block (that is the point — the breaker tripped because consecutive
 *     failures were recorded). This is the customer's per-agent local policy,
 *     not the platform. The platform check itself (evaluatorFn) is never
 *     reached when the breaker is OPEN.
 *   - Invariant 3 (graceful degradation): infra error on the breaker → ALLOW
 *     with advisory audit event. The SDK never throws.
 *
 * Usage:
 *   import { evaluatePreFlightWithBreaker } from './circuit-breaker-preflight.js';
 *
 *   const result = await evaluatePreFlightWithBreaker(
 *     { circuitBreaker, agentId, evaluatorFn, onAuditEvent },
 *     tenantId,
 *     requestBody,
 *   );
 *
 * @connexum/ai-governance  ASI-08 Cascading Failures — OWASP Agentic Top 10
 */
import { CircuitBreaker } from '../security/circuit-breaker.js';
export type GovernanceVerdict = 'ALLOW' | 'DENY' | 'PENDING';
export interface PackVerdictResult {
    verdict: GovernanceVerdict;
    triggeringPackIds: string[];
    triggeringClassifierIds: string[];
    reason: string;
    timestamp: number;
    approvalId?: string;
}
export type EvaluatorFn = (tenantId: string, agentId: string, toolName: string, args: Record<string, unknown>) => PackVerdictResult | Promise<PackVerdictResult>;
/**
 * Options for evaluatePreFlightWithBreaker.
 */
export interface BreakerAwareEvaluatorOptions {
    /**
     * Per-agent circuit breaker. When undefined/null the function acts as a
     * transparent pass-through to evaluatorFn (config opt-in not set).
     */
    circuitBreaker?: CircuitBreaker | undefined;
    /**
     * Stable agent identifier — used in audit events and DENY reasons.
     */
    agentId: string;
    /**
     * The downstream evaluator to call when the breaker is not OPEN.
     * Must return a PackVerdictResult or a Promise thereof.
     */
    evaluatorFn: EvaluatorFn;
    /**
     * Optional audit event callback. When provided, the function emits a
     * structured event through this callback (OWASP-tagged ASI-08) so the
     * caller can forward it to the audit chain / event bus.
     *
     * Signature: (eventName: string, data: Record<string, unknown>) => void
     *
     * Event names emitted:
     *   'circuit:breaker:tripped'   — breaker OPEN, tool call blocked (DENY)
     *   'circuit:breaker:advisory'  — breaker state store unavailable, fail-open
     */
    onAuditEvent?: (event: string, data: Record<string, unknown>) => void;
}
/**
 * Run the circuit-breaker check BEFORE the PreToolUse evaluatorFn.
 *
 * This is the default-on enforcement path for ASI-08.
 *
 * Behaviour matrix:
 *   circuitBreaker absent   → pass through to evaluatorFn (no-op).
 *   circuitBreaker CLOSED   → pass through to evaluatorFn.
 *   circuitBreaker OPEN     → DENY immediately; emit 'circuit:breaker:tripped'.
 *   circuitBreaker throws   → ALLOW (advisory fail-open); emit 'circuit:breaker:advisory'.
 */
export declare function evaluatePreFlightWithBreaker(opts: BreakerAwareEvaluatorOptions, tenantId: string, requestBody: Record<string, unknown>): Promise<PackVerdictResult>;
//# sourceMappingURL=circuit-breaker-preflight.d.ts.map