/**
 * Bounded, node-local HTTP concurrency calibration.
 *
 * This deliberately benchmarks a real application probe rather than CPU. A
 * database-bound API can have idle CPU while every request is waiting on I/O.
 * The caller chooses a representative, idempotent GET endpoint; ForgeZero's
 * cluster rehearsal uses its typed Arango read query.
 */
export interface CapacityStage {
    concurrency: number;
    requests: number;
    succeeded: number;
    failed: number;
    overloaded: number;
    /** Successful responses per second. This is the workload capacity signal. */
    successfulRequestsPerSecond: number;
    /** All attempts per second, retained to distinguish useful work from errors. */
    attemptedRequestsPerSecond: number;
    durationMs: number;
    errorRate: number;
    p95Ms: number;
    p99Ms: number;
    /** Whole-compute evidence sampled across this stage, not Agent-process CPU. */
    cpuUtilizationPercent: number;
    memoryUtilizationPercent: number;
}
export interface CapacityCalibration {
    endpoint: string;
    /** Highest sustained successful RPS observed at a stage that passed every bound. */
    measuredSustainableRequestsPerSecond: number;
    /** Admission ceiling derived from measured RPS and safetyRatio. */
    allowedRequestsPerSecond: number;
    safetyRatio: number;
    /** Secondary execution coordinate; never presented as request capacity. */
    recommendedConcurrency: number;
    stopReason: 'maximum-tested' | 'latency' | 'errors' | 'throughput-regression' | 'cpu' | 'memory';
    stages: CapacityStage[];
}
export interface CapacityCalibrationOptions {
    endpoint: string;
    maxConcurrency?: number;
    /** Minimum samples per worker before a stage may finish. */
    requestsPerWorker?: number;
    /** Hard request budget per worker. Defaults to 100 and can never exceed 100. */
    maximumRequestsPerWorker?: number;
    maxP95Ms?: number;
    maxErrorRate?: number;
    /** Defaults to 0.8: use at most 80% of measured sustainable RPS. */
    safetyRatio?: number;
    requestTimeoutMs?: number;
    minimumStageDurationMs?: number;
    maxCpuUtilizationPercent?: number;
    maxMemoryUtilizationPercent?: number;
}
export interface ValidatedCapacityCalibrationOptions {
    endpoint: URL;
    maxConcurrency: number;
    requestsPerWorker: number;
    maximumRequestsPerWorker: number;
    maxP95Ms: number;
    maxErrorRate: number;
    safetyRatio: number;
    requestTimeoutMs: number;
    minimumStageDurationMs: number;
    maxCpuUtilizationPercent: number;
    maxMemoryUtilizationPercent: number;
}
export interface HostCapacitySample {
    cpuIdle: number;
    cpuTotal: number;
    memoryUsed: number;
    memoryTotal: number;
}
type HostSampler = () => HostCapacitySample;
/** Only a service on this node may be stressed by an install-time probe. */
export declare function localCalibrationEndpoint(value: string): URL;
/** Parse every bound without sending a request; deploy definitions use this fail-closed gate. */
export declare function validateCapacityCalibrationOptions(options: CapacityCalibrationOptions): ValidatedCapacityCalibrationOptions;
/**
 * Increase load geometrically and stop at the first unsafe stage. The returned
 * limit is the last safe stage with explicit headroom; it is evidence, not a
 * promise that a different route or future release has the same capacity.
 */
export declare function calibrateHttpConcurrency(options: CapacityCalibrationOptions, fetcher?: typeof fetch, sampler?: HostSampler): Promise<CapacityCalibration>;
export {};