/**
 * @vauban-org/agent-sdk/testing/chaos — chaos harness (Sprint-475 / Sprint-477).
 *
 * Inject realistic failure patterns into a port impl to validate that
 * agents + resilience primitives (circuit breaker, idempotent, bulkhead)
 * behave correctly under adverse conditions. Not to be used in production.
 *
 * Public API (Sprint-477):
 *   injectBrainFailure<P>(port, { failureRate, type? }) — BrainPort-aware wrapper
 *   networkJitter<P>(port, { p99Ms, p50Ms? })           — latency injection
 *   wholeCircuit<P>(port)                               — trips every call (half-open testing)
 *   exhaustResources<P>(port, { maxCalls })             — throws after N calls
 *
 * Legacy API (Sprint-475 — kept for backward compat):
 *   injectFailure<T>(impl, opts)  — generic failure injection
 *   fullOutage<T>(impl, opts)     — rate=1 shorthand
 *
 * Usage (vitest):
 *   import { injectBrainFailure, networkJitter } from "@vauban-org/agent-sdk/testing/chaos";
 *   const flaky = injectBrainFailure(brain, { failureRate: 0.3, type: "rate-limit" });
 *   const slow  = networkJitter(brain, { p99Ms: 500, p50Ms: 50 });
 */
import type { BrainPort } from "../ports/index.js";
export type FailureType = "rate-limit" | "timeout" | "network" | "random" | "unavailable" | "error";
export interface InjectFailureOptions {
    /** 0..1 probability that a call fails instead of delegating. */
    rate: number;
    /**
     * Optional factory that produces the Error to throw. Defaults based
     * on `type` (rate-limit -> BrainRateLimit, else BrainUnavailable).
     */
    err?: () => Error;
    /** Shortcut for common error types. */
    type?: FailureType;
    /** Optional PRNG (defaults to Math.random). Inject for deterministic tests. */
    random?: () => number;
}
/**
 * Wrap every function-valued method of `impl` so `rate` fraction of
 * calls throw. Non-function properties pass through unchanged.
 */
export declare function injectFailure<T extends object>(impl: T, options: InjectFailureOptions): T;
export interface NetworkJitterOptions {
    /** Minimum delay per call, in ms. Default 0. */
    minMs?: number;
    /** Maximum delay per call, in ms. Default 100. */
    maxMs?: number;
    /**
     * p99 latency in ms (Sprint-477 API). When set, models a log-normal
     * distribution where ~99% of calls complete within p99Ms.
     * If both legacy (minMs/maxMs) and new (p99Ms) options are provided,
     * p99Ms takes precedence.
     */
    p99Ms?: number;
    /**
     * p50 (median) latency in ms. Only meaningful when p99Ms is set.
     * Defaults to p99Ms / 10 (rough estimate for a log-normal dist).
     */
    p50Ms?: number;
    /** Optional uniform PRNG for test determinism. */
    random?: () => number;
}
/**
 * Wrap every method so async calls settle after a random delay.
 *
 * Two usage modes:
 *   networkJitter(port, { minMs: 10, maxMs: 100 })          — uniform [min,max]
 *   networkJitter(port, { p99Ms: 500, p50Ms: 50 })          — log-normal percentile model
 *
 * Combined with bulkhead, proves queue stays bounded under slow backends.
 */
export declare function networkJitter<T extends object>(impl: T, options?: NetworkJitterOptions): T;
export interface OutageOptions {
    /** Error factory for every call. */
    err?: () => Error;
}
/**
 * Every call throws. Useful to probe "brain down" degradation paths —
 * pairs with circuitBreaker to assert the breaker trips promptly.
 */
export declare function fullOutage<T extends object>(impl: T, options?: OutageOptions): T;
export interface InjectBrainFailureOptions {
    /** 0..1 probability that any call fails. */
    failureRate: number;
    /** Error type to inject. Default "rate-limit". */
    type?: "rate-limit" | "timeout" | "network" | "random";
    /** Optional PRNG for deterministic tests. */
    random?: () => number;
}
/**
 * BrainPort-specific chaos wrapper. Semantically equivalent to
 * injectFailure but typed against BrainPort and uses BrainPort-aware
 * defaults (rate-limit → BrainRateLimit instead of generic error).
 *
 * Usage:
 *   const flaky = injectBrainFailure(brain, { failureRate: 0.3, type: "rate-limit" });
 *   // Use in narrator tests to assert Brain-dependent steps are skipped.
 */
export declare function injectBrainFailure<P extends BrainPort>(port: P, opts: InjectBrainFailureOptions): P;
/**
 * Trips every call immediately (rate=1, BrainUnavailable). Designed for
 * half-open testing: wrap the port BEFORE passing it to circuitBreaker,
 * then advance the clock past resetAfterMs to trigger the HALF-OPEN probe.
 *
 *   const cb = circuitBreaker(wholeCircuit(brain).archiveKnowledge.bind(...), {
 *     failureThreshold: 1,
 *     resetAfterMs: 1_000,
 *     now: () => clock,
 *   });
 */
export declare function wholeCircuit<P extends object>(port: P): P;
export interface ExhaustResourcesOptions {
    /** Number of successful calls before throwing. */
    maxCalls: number;
    /** Error factory for calls past the limit. Default: BrainUnavailable. */
    err?: () => Error;
}
/**
 * Allow the first `maxCalls` invocations to succeed, then throw on
 * every subsequent call. Simulates quota exhaustion or memory pressure.
 *
 * Counter is shared across all methods — useful to cap total call volume
 * in property tests regardless of which method is invoked.
 */
export declare function exhaustResources<P extends object>(port: P, opts: ExhaustResourcesOptions): P;
//# sourceMappingURL=chaos.d.ts.map