from __future__ import annotations

import json
from pathlib import Path
from typing import Any

from .lca import EPSILON, WorkloadProfile
from .spec import ConfigPatch, Proposal, StudySpec, StudyState, TrialSummary


_TOPOLOGY_KEYS = {
    "tensor-parallel-size",
    "data-parallel-size",
    "expert-parallel-size",
    "enable-expert-parallel",
}
_RUNTIME_KEYS = {
    "max-num-seqs",
    "max-num-batched-tokens",
    "block-size",
    "gpu-memory-utilization",
    "enable-chunked-prefill",
}
_STRONG_INCUMBENT_MIN_GAIN = 1.8
_MIN_POST_INCUMBENT_VALIDATION_TRIALS = 2
_VALIDATION_TRIALS_WITHOUT_FAMILY_COVERAGE = 3


def build_harness_context(
    *,
    study: StudySpec,
    window_summary: dict[str, Any],
    state: StudyState,
    workload_profile: WorkloadProfile | None = None,
) -> dict[str, Any]:
    recent_diagnostics = _recent_trial_diagnostics(state)
    trial_profiles = _trial_profiles(study, recent_diagnostics)
    bottleneck_hypotheses = _rank_bottleneck_hypotheses(
        study,
        window_summary,
        trial_profiles,
    )
    experiment_plan = _experiment_plan(
        study,
        window_summary,
        state,
        recent_diagnostics,
        trial_profiles,
        bottleneck_hypotheses,
    )
    return {
        "paper_alignment": {
            "goal": "Use workload-feature-to-knob harnesses to reduce wasted trials and avoid regressing after a good configuration is found.",
            "feature_model": "L-C-A: request lengths, inter-request KV-cache reuse, and arrival dynamics.",
            "trial_policy": "Profile measured trials, rank bottleneck hypotheses, score generic candidate actions, and stop only when no useful measured hypothesis remains.",
        },
        "workload_lca_profile": _workload_lca_profile(window_summary, workload_profile),
        "recent_trial_diagnostics": recent_diagnostics,
        "trial_profiles": trial_profiles,
        "bottleneck_hypotheses": bottleneck_hypotheses,
        "candidate_actions": experiment_plan["candidate_actions"],
        "experiment_plan": experiment_plan,
        "convergence_guard": _convergence_guard(state, recent_diagnostics),
        "harness_stop": _harness_stop_decision(
            study,
            state,
            recent_diagnostics,
            experiment_plan=experiment_plan,
        ),
        "harness_proposal": _harness_proposal_decision(
            study,
            window_summary,
            state,
            recent_diagnostics,
            experiment_plan=experiment_plan,
        ),
        "knob_harnesses": _knob_harnesses(study, window_summary, recent_diagnostics),
        "proposal_rules": _proposal_rules(),
    }


def build_harness_stop_proposal(context: dict[str, Any]) -> Proposal | None:
    stop = context.get("harness_stop")
    if not isinstance(stop, dict) or not stop.get("should_stop"):
        return None
    reason = str(stop.get("reason") or "harness_converged")
    evidence = stop.get("evidence") if isinstance(stop.get("evidence"), dict) else {}
    observation = (
        "Harness convergence guard triggered before requesting another proposal: "
        f"{reason}."
    )
    diagnosis = str(evidence.get("summary") or reason)
    return Proposal(
        observation=observation,
        diagnosis=diagnosis,
        config_patch=ConfigPatch(env_patch={}, flag_patch={}),
        expected_effects=[
            "stop without spending another GPU trial",
            "preserve the current best observed configuration",
        ],
        why_not_previous_failures=(
            "The stop decision is based on completed validation evidence and does not "
            "repeat any failed configuration."
        ),
        should_stop=True,
    )


def build_harness_guided_proposal(context: dict[str, Any]) -> Proposal | None:
    proposal = context.get("harness_proposal")
    if not isinstance(proposal, dict) or not proposal.get("should_propose"):
        return None
    patch = proposal.get("config_patch")
    if not isinstance(patch, dict):
        return None
    flag_patch = patch.get("flag_patch")
    env_patch = patch.get("env_patch")
    if not isinstance(flag_patch, dict) or not isinstance(env_patch, dict):
        return None
    reason = str(proposal.get("reason") or "harness_guided_probe")
    diagnosis = str(proposal.get("diagnosis") or reason)
    return Proposal(
        observation=(
            "Harness selected a deterministic first validation probe before "
            f"requesting an LLM proposal: {reason}."
        ),
        diagnosis=diagnosis,
        config_patch=ConfigPatch(env_patch=dict(env_patch), flag_patch=dict(flag_patch)),
        expected_effects=[
            str(item)
            for item in proposal.get("expected_effects", [])
            if isinstance(item, str)
        ],
        why_not_previous_failures=(
            "The proposal is based on the first completed baseline trial and does not "
            "repeat a prior failed configuration."
        ),
        should_stop=False,
    )


def render_harness_context(context: dict[str, Any]) -> str:
    return json.dumps(context, ensure_ascii=False, indent=2)


def _workload_lca_profile(
    window_summary: dict[str, Any],
    workload_profile: WorkloadProfile | None = None,
) -> dict[str, Any]:
    if workload_profile is not None:
        return _canonical_lca_profile(workload_profile)
    prefix_cache = window_summary.get("prefix_cache")
    if not isinstance(prefix_cache, dict):
        prefix_cache = {}
    prompt_p50 = _as_float(window_summary.get("prompt_tokens_p50"))
    prompt_p95 = _as_float(window_summary.get("prompt_tokens_p95"))
    prompt_p99 = _as_float(window_summary.get("prompt_tokens_p99"))
    tail_ratio = _as_float(window_summary.get("prompt_tail_ratio_p95_p50"))
    repeated_token_ratio = _as_float(prefix_cache.get("repeated_token_ratio_estimate"))
    burst_ratio = _as_float(window_summary.get("arrival_burst_ratio_p95_to_mean"))
    interarrival_cv = _as_float(window_summary.get("arrival_interarrival_cv"))
    return {
        "L_request_lengths": {
            "prompt_tokens_p50": prompt_p50,
            "prompt_tokens_p95": prompt_p95,
            "prompt_tokens_p99": prompt_p99,
            "tail_ratio_p95_p50": tail_ratio,
            "regime": _length_regime(prompt_p95, tail_ratio),
        },
        "C_prefix_cache": {
            "repeated_token_ratio_estimate": repeated_token_ratio,
            "repeated_block_ratio": _as_float(prefix_cache.get("repeated_block_ratio")),
            "multi_turn_request_ratio": _as_float(prefix_cache.get("multi_turn_request_ratio")),
            "rows_with_hash_ids": int(prefix_cache.get("rows_with_hash_ids") or 0),
            "regime": _cache_regime(repeated_token_ratio),
        },
        "A_arrivals": {
            "request_rate": _as_float(window_summary.get("request_rate")),
            "qps_1s_p50": _as_float(window_summary.get("arrival_qps_1s_p50")),
            "qps_1s_p95": _as_float(window_summary.get("arrival_qps_1s_p95")),
            "burst_ratio_p95_to_mean": burst_ratio,
            "interarrival_cv": interarrival_cv,
            "regime": _arrival_regime(burst_ratio, interarrival_cv),
        },
    }


def _canonical_lca_profile(profile: WorkloadProfile) -> dict[str, Any]:
    """Authoritative L-C-A block: the paper's 10-dim RobustScaler vector.

    Sourced from lca.WorkloadProfile so the prompt's L-C-A is the same metric
    used for the workload-similarity computations, not an ad-hoc re-derivation.
    The regime labels reuse the heuristic classifiers but are fed from the
    canonical stats.
    """
    stats = profile.stats if isinstance(profile.stats, dict) else {}
    length = stats.get("length") if isinstance(stats.get("length"), dict) else {}
    cache = stats.get("cache") if isinstance(stats.get("cache"), dict) else {}
    arrival = stats.get("arrival") if isinstance(stats.get("arrival"), dict) else {}
    length_p95 = _as_float(length.get("p95"))
    length_p50 = _as_float(length.get("p50"))
    tail_ratio = float(length_p95 / max(length_p50, EPSILON)) if length_p95 else 0.0
    repeated_token_ratio = _as_float(cache.get("input_hit_rate"))
    fano_1s = _as_float(arrival.get("fano_1s"))
    interarrival_cv = _as_float(arrival.get("interarrival_cv"))
    return {
        "metric": "paper L-C-A (10-dim, RobustScaler-normalized) from lca.WorkloadProfile",
        "length_mode": profile.length_mode,
        "feature_names": list(profile.feature_names),
        "vector": list(profile.vector),
        "L_request_lengths": {
            "mean": _as_float(length.get("mean")),
            "p50": length_p50,
            "p95": length_p95,
            "cv": _as_float(length.get("cv")),
            "tail_ratio_p95_p50": tail_ratio,
            "regime": _length_regime(length_p95, tail_ratio),
        },
        "C_prefix_cache": {
            "hit_rate": _as_float(cache.get("hit_rate")),
            "input_hit_rate": repeated_token_ratio,
            "repeated_block_ratio": _as_float(cache.get("repeated_block_ratio")),
            "rows_with_hash_ids": int(cache.get("rows_with_hash_ids") or 0),
            "regime": _cache_regime(repeated_token_ratio),
        },
        "A_arrivals": {
            "request_rate": _as_float(arrival.get("request_rate")),
            "request_rate_per_gpu": _as_float(arrival.get("request_rate_per_gpu")),
            "interarrival_cv": interarrival_cv,
            "fano_1s": fano_1s,
            "regime": _arrival_regime(fano_1s, interarrival_cv),
        },
    }


def _knob_harnesses(
    study: StudySpec,
    window_summary: dict[str, Any],
    recent_diagnostics: list[dict[str, Any]],
) -> list[dict[str, Any]]:
    tunable = set(study.engine.tunable_flags)
    latest = recent_diagnostics[-1] if recent_diagnostics else {}
    active_bottleneck = latest.get("active_bottleneck") or _workload_default_bottleneck(
        study, window_summary
    )
    harnesses: list[dict[str, Any]] = []
    if "tensor-parallel-size" in tunable:
        harnesses.append(
            {
                "knob_family": "tensor-parallel-size",
                "use_when": [
                    "TTFT failures dominate, especially on long prompt windows.",
                    "The L profile has a heavy tail and prefill service time is the likely bottleneck.",
                    "For decode-only studies, TP/DP redistribution can be the primary way to trade per-request decode latency against GPU-parallel serving replicas.",
                ],
                "procedure": [
                    "Probe only adjacent legal TP choices around the incumbent topology.",
                    "Prefer TP up when it lowers long-prefill latency and the projected request rate remains left of the high-TP queueing knee.",
                    "For decode_tpot bottlenecks, compare legal TP/DP redistributions using request_rate_per_gpu and SLO pass rate; prefer smaller TP with larger DP only when the model fits and observed TPOT remains within the configured SLO.",
                    "Prefer TP down or keep moderate TP when communication overhead or concurrency loss becomes visible.",
                ],
                "guards": [
                    "Do not jump across multiple TP values without a launch-safe reason.",
                    "Do not raise TP for a short-prompt/cache-heavy window if TTFT is already passing and TPOT or queueing is the active bottleneck, unless decode-only TPOT evidence points to under-parallelized decoding.",
                    "Keep TP/DP/EP inside topology_constraints.",
                ],
                "active_now": active_bottleneck in {"ttft_prefill", "decode_tpot"},
            }
        )
    if "data-parallel-size" in tunable:
        harnesses.append(
            {
                "knob_family": "data-parallel-size",
                "use_when": [
                    "Decode-only or cache-heavy workloads need more independent replicas after TTFT is no longer the limiting objective.",
                    "The active bottleneck is decode_tpot or admission/queueing and topology_constraints allow a legal TP/DP redistribution.",
                ],
                "procedure": [
                    "Change DP only as part of a legal adjacent TP/DP topology move when the product constraints require coupling.",
                    "Evaluate the candidate by request_rate_per_gpu, configured TPOT/TTFT pass rate, and launch stability; do not optimize raw request rate alone.",
                    "Use previous same-topology or adjacent-topology history to decide whether DP improved admission without making token latency infeasible.",
                ],
                "guards": [
                    "Do not reduce TP so far that decode_tpot failures dominate the configured SLO.",
                    "Do not repeat a topology whose launch failure implicated TP/DP/EP.",
                    "Keep TP/DP/EP inside topology_constraints.",
                ],
                "active_now": active_bottleneck in {"decode_tpot", "admission_or_queueing"},
            }
        )
    if "max-num-seqs" in tunable:
        harnesses.append(
            {
                "knob_family": "max-num-seqs",
                "use_when": [
                    "Prefix-cache reuse is high, requests are short-to-moderate after cache hits, and queueing/admission is limiting throughput.",
                    "TTFT is mostly passing but offered load stalls below the target.",
                    "For decode_tpot bottlenecks, decode concurrency is too high or too low relative to the configured TPOT SLO and observed pass-rate headroom.",
                ],
                "procedure": [
                    "Increase max-num-seqs one step at a time to exploit cache-created parallelism.",
                    "For decode_tpot, lower max-num-seqs when TPOT failures dominate; raise it only when the incumbent has SLO headroom and admission/queueing limits throughput.",
                    "Decrease it if p95 TTFT worsens, prefill queueing appears, TPOT failures dominate, or memory pressure causes launch/runtime failures.",
                ],
                "guards": [
                    "Avoid large max-num-seqs increases on low-cache or heavy-tail windows.",
                    "Do not combine a max-num-seqs jump with a TP jump unless the history clearly isolates both bottlenecks.",
                ],
                "active_now": active_bottleneck in {"decode_tpot", "admission_or_queueing"},
            }
        )
    if "max-num-batched-tokens" in tunable:
        harnesses.append(
            {
                "knob_family": "max-num-batched-tokens",
                "use_when": [
                    "Prefill batching is too small for the L profile or TTFT is hurt by excessive chunking overhead.",
                    "GPU work appears fragmented and the incumbent is stable but under-utilized.",
                    "For decode-only workloads, decode batching pressure affects TPOT pass rate after topology is stable.",
                ],
                "procedure": [
                    "Raise MBT for long prompts when memory headroom and SLO permit.",
                    "Lower MBT if long requests monopolize batches and short-request TTFT regresses.",
                    "For decode_tpot, lower MBT when token-latency failures dominate and raise it only when SLO headroom and under-utilization are both observed.",
                ],
                "guards": [
                    "Keep MBT changes within a conservative trust region.",
                    "Do not raise MBT after OOM or launch failures involving memory-related knobs.",
                    "Do not raise MBT when the incumbent MBT already covers prompt p99 unless same-topology history proves prefill fragmentation is the bottleneck.",
                ],
                "active_now": active_bottleneck in {"ttft_prefill", "decode_tpot"},
            }
        )
    if "enable-chunked-prefill" in tunable:
        harnesses.append(
            {
                "knob_family": "enable-chunked-prefill",
                "use_when": [
                    "The L profile has a long tail and long prefills block shorter requests.",
                ],
                "procedure": [
                    "Keep chunked prefill enabled for heavy-tail chat windows unless history shows chunking overhead dominates.",
                ],
                "guards": [
                    "Do not disable chunked prefill on a heavy-tail workload without direct evidence from a nearby trial.",
                ],
                "active_now": False,
            }
        )
    if "expert-parallel-size" in tunable or "enable-expert-parallel" in tunable:
        harnesses.append(
            {
                "knob_family": "expert-parallel",
                "use_when": [
                    "Only when history or a capability profile identifies expert communication or MoE dispatch as the active bottleneck.",
                    "For MoE decode-only studies, retain an already valid EP topology when it is part of the baseline constraints or prior best, but change EP only with direct adjacent evidence.",
                ],
                "procedure": [
                    "Keep expert parallel disabled for pure TTFT/prefill tuning unless there is direct positive evidence for EP on this stack.",
                    "For decode_tpot, preserve the current effective EP setting unless the nearby history shows EP-specific token-latency or launch behavior is the limiting factor.",
                    "If EP is tested, change only EP-related knobs and treat launch/runtime failure as hard negative evidence.",
                ],
                "guards": [
                    "Do not introduce EP as the first follow-up after a successful TP increase.",
                    "Do not use EP to address generic TTFT-prefill bottlenecks; TP and batching harnesses are the relevant families.",
                    "Do not change EP size for a decode-only run just to search broader topology space; require EP-specific evidence or a topology constraint that forces the current EP.",
                    "Do not enable EP after any launch failure involving expert-parallel knobs.",
                ],
                "active_now": False,
            }
        )
    if "gpu-memory-utilization" in tunable:
        harnesses.append(
            {
                "knob_family": "gpu-memory-utilization",
                "use_when": [
                    "The engine launches cleanly but memory headroom limits batching.",
                ],
                "procedure": [
                    "Make small adjustments only after topology and batching knobs are stable.",
                ],
                "guards": [
                    "Treat launch OOM as hard negative evidence and back off immediately.",
                ],
                "active_now": False,
            }
        )
    return harnesses


def _recent_trial_diagnostics(state: StudyState) -> list[dict[str, Any]]:
    diagnostics: list[dict[str, Any]] = []
    for trial in state.trials[-stateful_history_limit() :]:
        item: dict[str, Any] = {
            "trial_id": trial.trial_id,
            "status": trial.status,
            "parallel_size": trial.parallel_size,
            "best_request_rate": trial.best_request_rate,
            "best_request_rate_per_gpu": trial.best_request_rate_per_gpu,
            "best_pass_rate": trial.best_pass_rate,
            "diagnosis": trial.diagnosis,
            "config_patch": trial.config_patch,
            "failure_stage": trial.failure_stage,
            "failure_reason": trial.failure_reason,
        }
        result = _load_result(trial)
        if result:
            probes = result.get("probes")
            if isinstance(probes, list) and probes:
                best_probe = _best_feasible_probe(probes)
                last_probe = probes[-1] if isinstance(probes[-1], dict) else None
                item["probe_summary"] = {
                    "best_feasible_probe": _compact_probe(best_probe),
                    "last_probe": _compact_probe(last_probe),
                }
                item["active_bottleneck"] = _active_bottleneck_from_probe_sequence(
                    probes,
                    fallback=best_probe or last_probe,
                )
            elif result.get("all_infeasible_diagnostics"):
                diag = result["all_infeasible_diagnostics"]
                item["probe_summary"] = {"all_infeasible": diag}
                item["active_bottleneck"] = _active_bottleneck({"payload": diag})
        else:
            item["active_bottleneck"] = _failure_bottleneck(trial)
        diagnostics.append(item)
    return diagnostics


def _trial_profiles(
    study: StudySpec,
    recent_diagnostics: list[dict[str, Any]],
) -> list[dict[str, Any]]:
    profiles: list[dict[str, Any]] = []
    for item in recent_diagnostics:
        flags = _effective_flags_for_item(study, item)
        probe_summary = item.get("probe_summary")
        best_probe = None
        last_probe = None
        all_infeasible = None
        if isinstance(probe_summary, dict):
            best_probe = probe_summary.get("best_feasible_probe")
            last_probe = probe_summary.get("last_probe")
            all_infeasible = probe_summary.get("all_infeasible")
        limiting_probe = (
            last_probe
            if isinstance(last_probe, dict)
            else all_infeasible
            if isinstance(all_infeasible, dict)
            else best_probe
            if isinstance(best_probe, dict)
            else None
        )
        latency = limiting_probe.get("latency_summary") if isinstance(limiting_probe, dict) else {}
        if not isinstance(latency, dict):
            latency = {}
        failed_counts = latency.get("failed_reason_counts")
        if not isinstance(failed_counts, dict):
            failed_counts = {}
        profile = {
            "trial_id": item.get("trial_id"),
            "status": item.get("status"),
            "config_patch": item.get("config_patch") if isinstance(item.get("config_patch"), dict) else {},
            "topology": {
                "tensor_parallel_size": _parse_int_like(
                    flags.get("tensor-parallel-size"),
                    default=1,
                ),
                "data_parallel_size": _parse_int_like(
                    flags.get("data-parallel-size"),
                    default=1,
                ),
                "expert_parallel_size": _parse_int_like(
                    flags.get("expert-parallel-size"),
                    default=1,
                ),
                "enable_expert_parallel": bool(flags.get("enable-expert-parallel", False)),
            },
            "performance": {
                "best_request_rate": item.get("best_request_rate"),
                "best_request_rate_per_gpu": item.get("best_request_rate_per_gpu"),
                "best_pass_rate": item.get("best_pass_rate"),
            },
            "probe_profile": {
                "best_feasible_probe": best_probe,
                "limiting_probe": limiting_probe,
                "active_bottleneck": item.get("active_bottleneck"),
                "failed_reason_counts": failed_counts,
                "latency_quantiles": {
                    "ttft_ms": latency.get("ttft_ms") if isinstance(latency.get("ttft_ms"), dict) else {},
                    "tpot_ms": latency.get("tpot_ms") if isinstance(latency.get("tpot_ms"), dict) else {},
                },
            },
            "failure_profile": {
                "failure_stage": item.get("failure_stage"),
                "failure_reason": item.get("failure_reason"),
            },
        }
        profiles.append(profile)
    return profiles


def _rank_bottleneck_hypotheses(
    study: StudySpec,
    window_summary: dict[str, Any],
    trial_profiles: list[dict[str, Any]],
) -> list[dict[str, Any]]:
    scores = {
        "ttft_prefill": 0.0,
        "decode_tpot": 0.0,
        "admission_or_queueing": 0.0,
        "launch_or_memory": 0.0,
    }
    evidence: dict[str, list[str]] = {name: [] for name in scores}

    default = _workload_default_bottleneck(study, window_summary)
    if default in scores:
        scores[default] += 0.18
        evidence[default].append(f"workload default bottleneck is {default}")

    if study.trace.request_mode == "decode_only" and study.slo.tpot_rule is not None:
        scores["decode_tpot"] += 0.22
        evidence["decode_tpot"].append("decode_only study with configured TPOT SLO")
    if study.slo.ttft_rule is not None:
        prompt_p95 = _as_float(window_summary.get("prompt_tokens_p95"))
        if prompt_p95 >= 4096:
            scores["ttft_prefill"] += 0.14
            evidence["ttft_prefill"].append("long prompt p95 makes TTFT/prefill plausible")

    for profile in trial_profiles[-stateful_history_limit() :]:
        active = str(profile.get("probe_profile", {}).get("active_bottleneck") or "")
        if active in scores:
            weight = 0.34 if profile is trial_profiles[-1] else 0.18
            scores[active] += weight
            evidence[active].append(
                f"{profile.get('trial_id')} probe diagnosis is {active}"
            )
        failed = profile.get("probe_profile", {}).get("failed_reason_counts")
        if not isinstance(failed, dict):
            failed = {}
        ttft_count = sum(int(v) for k, v in failed.items() if str(k).startswith("ttft"))
        tpot_count = sum(int(v) for k, v in failed.items() if str(k).startswith("tpot"))
        elapsed_count = sum(
            int(v)
            for k, v in failed.items()
            if str(k).startswith("probe_elapsed_s>")
            or str(k).startswith("arrival_lag_s>")
        )
        total = max(ttft_count + tpot_count + elapsed_count, 1)
        if ttft_count:
            scores["ttft_prefill"] += min(0.24, 0.24 * ttft_count / total)
            evidence["ttft_prefill"].append(
                f"{profile.get('trial_id')} TTFT failures={ttft_count}"
            )
        if tpot_count:
            scores["decode_tpot"] += min(0.24, 0.24 * tpot_count / total)
            evidence["decode_tpot"].append(
                f"{profile.get('trial_id')} TPOT failures={tpot_count}"
            )
        if elapsed_count:
            scores["admission_or_queueing"] += min(0.18, 0.18 * elapsed_count / total)
            evidence["admission_or_queueing"].append(
                f"{profile.get('trial_id')} queue/elapsed failures={elapsed_count}"
            )
        failure_stage = str(profile.get("failure_profile", {}).get("failure_stage") or "")
        failure_reason = str(profile.get("failure_profile", {}).get("failure_reason") or "")
        if failure_stage == "engine_launch" or "out of memory" in failure_reason.lower():
            scores["launch_or_memory"] += 0.4
            evidence["launch_or_memory"].append(
                f"{profile.get('trial_id')} launch or memory failure"
            )

    ranked = []
    for name, score in scores.items():
        if score <= 0:
            continue
        ranked.append(
            {
                "name": name,
                "confidence": min(0.99, round(score, 4)),
                "evidence": evidence[name][:6],
            }
        )
    ranked.sort(key=lambda item: item["confidence"], reverse=True)
    return ranked


def stateful_history_limit() -> int:
    return 8


def _load_result(trial: TrialSummary) -> dict[str, Any] | None:
    if not trial.result_path:
        return None
    path = Path(trial.result_path)
    if not path.exists():
        return None
    try:
        payload = json.loads(path.read_text(encoding="utf-8"))
    except (OSError, json.JSONDecodeError):
        return None
    return payload if isinstance(payload, dict) else None


def _best_feasible_probe(probes: list[Any]) -> dict[str, Any] | None:
    best: dict[str, Any] | None = None
    for probe in probes:
        if not isinstance(probe, dict) or not probe.get("feasible"):
            continue
        payload = probe.get("payload")
        if not isinstance(payload, dict):
            continue
        if best is None:
            best = probe
            continue
        best_payload = best.get("payload") if isinstance(best.get("payload"), dict) else {}
        if _as_float(payload.get("request_rate")) > _as_float(best_payload.get("request_rate")):
            best = probe
    return best


def _compact_probe(probe: dict[str, Any] | None) -> dict[str, Any] | None:
    if not isinstance(probe, dict):
        return None
    payload = probe.get("payload")
    if not isinstance(payload, dict):
        payload = probe
    return {
        "threshold": probe.get("threshold", payload.get("threshold")),
        "feasible": probe.get("feasible", payload.get("feasible")),
        "request_count": payload.get("request_count"),
        "pass_rate": payload.get("pass_rate"),
        "request_rate": payload.get("request_rate"),
        "early_stopped": payload.get("early_stopped"),
        "early_stop_reason": payload.get("early_stop_reason"),
        "latency_summary": payload.get("latency_summary"),
    }


def _active_bottleneck(probe: dict[str, Any] | None) -> str:
    compact = _compact_probe(probe)
    if not compact:
        return "unknown"
    early_stop_reason = str(compact.get("early_stop_reason") or "")
    if early_stop_reason.startswith("arrival_lag_s>"):
        return "admission_or_queueing"
    latency_summary = compact.get("latency_summary")
    if not isinstance(latency_summary, dict):
        if early_stop_reason == "slo_pass_rate_unrecoverable":
            return "admission_or_queueing"
        return "unknown"
    failed = latency_summary.get("failed_reason_counts")
    if not isinstance(failed, dict) or not failed:
        if early_stop_reason == "slo_pass_rate_unrecoverable":
            return "admission_or_queueing"
        return "none_obvious"
    ttft_count = sum(int(v) for k, v in failed.items() if str(k).startswith("ttft"))
    tpot_count = sum(int(v) for k, v in failed.items() if str(k).startswith("tpot"))
    request_failed_count = sum(
        int(v)
        for k, v in failed.items()
        if not str(k).startswith("ttft")
        and not str(k).startswith("tpot")
        and not str(k).startswith("probe_elapsed_s>")
        and str(k) != "slo_pass_rate_unrecoverable"
    )
    if ttft_count == 0 and tpot_count == 0 and request_failed_count == 0:
        return "none_obvious"
    if ttft_count >= max(tpot_count, request_failed_count):
        return "ttft_prefill"
    if tpot_count >= max(ttft_count, request_failed_count):
        return "decode_tpot"
    return "admission_or_queueing"


def _active_bottleneck_from_probe_sequence(
    probes: list[Any],
    *,
    fallback: dict[str, Any] | None,
) -> str:
    for probe in reversed(probes):
        if not isinstance(probe, dict):
            continue
        bottleneck = _active_bottleneck(probe)
        if bottleneck not in {"unknown", "none_obvious"}:
            return bottleneck
    return _active_bottleneck(fallback)


def _failure_bottleneck(trial: TrialSummary) -> str:
    if trial.failure_stage == "engine_launch":
        return "launch_or_memory"
    if trial.failure_reason:
        return "runtime_failure"
    return "unknown"


def _convergence_guard(
    state: StudyState,
    recent_diagnostics: list[dict[str, Any]],
) -> dict[str, Any]:
    infeasible_progress = _infeasible_progress_guard(recent_diagnostics)
    strong_incumbent = _strong_incumbent_guard(state, recent_diagnostics)
    completed = [
        item
        for item in recent_diagnostics
        if item.get("status") == "completed"
        and isinstance(item.get("best_request_rate_per_gpu"), (int, float))
    ]
    should_stop = False
    reason = "insufficient_completed_trials"
    if len(completed) >= 3 and state.best_request_rate_per_gpu is not None:
        recent_rates = [float(item["best_request_rate_per_gpu"]) for item in completed[-3:]]
        best = float(state.best_request_rate_per_gpu)
        near_best = [rate >= best * 0.98 for rate in recent_rates]
        if all(near_best):
            should_stop = True
            reason = "last_three_completed_trials_are_within_2_percent_of_incumbent"
        else:
            reason = "recent_trials_still_show_material_variation"
    elif state.best_request_rate_per_gpu is not None:
        reason = "need_more_evidence_before_stop"
    if not should_stop and infeasible_progress["plateau_detected"]:
        reason = str(infeasible_progress["reason"])
    if (
        not should_stop
        and not infeasible_progress["plateau_detected"]
        and strong_incumbent["guard_active"]
    ):
        reason = "strong_incumbent_requires_validation_probes"
    return {
        "deterministic_stop": should_stop,
        "should_stop_if_no_harness_can_justify_a_new_adjacent_probe": (
            should_stop
            or bool(infeasible_progress["stop_if_next_probe_repeats_family"])
        ),
        "reason": reason,
        "infeasible_progress": infeasible_progress,
        "strong_incumbent": strong_incumbent,
        "incumbent": {
            "trial_id": state.best_trial_id,
            "parallel_size": state.best_parallel_size,
            "best_sampling_u": state.best_sampling_u,
            "best_request_rate": state.best_request_rate,
            "best_request_rate_per_gpu": state.best_request_rate_per_gpu,
        },
    }


def _harness_stop_decision(
    study: StudySpec,
    state: StudyState,
    recent_diagnostics: list[dict[str, Any]],
    *,
    experiment_plan: dict[str, Any] | None = None,
) -> dict[str, Any]:
    high_saturation = _search_high_saturation_guard(study, state, recent_diagnostics)
    if high_saturation["saturated"]:
        return {
            "should_stop": True,
            "reason": high_saturation["reason"],
            "evidence": high_saturation,
        }
    topology_frontier = _topology_frontier_status(study, state, recent_diagnostics)
    if topology_frontier["frontier_open"]:
        return {
            "should_stop": False,
            "reason": "topology_frontier_requires_probe",
            "evidence": topology_frontier,
        }
    if experiment_plan is not None and experiment_plan.get("next_action"):
        action = experiment_plan["next_action"]
        if isinstance(action, dict) and _as_float(action.get("score")) >= 0.35:
            return {
                "should_stop": False,
                "reason": "experiment_plan_has_high_value_candidate",
                "evidence": {
                    "summary": "The profile-driven planner still has a useful measured hypothesis to test.",
                    "next_action": action,
                },
            }
    guard = _convergence_guard(state, recent_diagnostics)
    if guard["deterministic_stop"]:
        return {
            "should_stop": True,
            "reason": guard["reason"],
            "evidence": {
                "summary": "The convergence guard fired and no further adjacent probe is required.",
                "convergence_guard": guard,
            },
        }
    validation = _validation_exhausted_guard(state, recent_diagnostics)
    if validation["exhausted"]:
        return {
            "should_stop": True,
            "reason": validation["reason"],
            "evidence": validation,
        }
    return {
        "should_stop": False,
        "reason": "continue_harness_guided_search",
        "evidence": {
            "summary": "No deterministic harness stop condition is satisfied.",
            "search_high_saturation": high_saturation,
            "convergence_guard": guard,
            "validation_exhausted": validation,
        },
    }


def _harness_proposal_decision(
    study: StudySpec,
    window_summary: dict[str, Any],
    state: StudyState,
    recent_diagnostics: list[dict[str, Any]],
    *,
    experiment_plan: dict[str, Any] | None = None,
) -> dict[str, Any]:
    default = {
        "should_propose": False,
        "reason": "no_deterministic_harness_proposal",
        "diagnosis": "Defer to the LLM proposal policy.",
        "config_patch": {"env_patch": {}, "flag_patch": {}},
        "expected_effects": [],
    }
    tested_signatures = {
        _config_signature(item.get("config_patch") if isinstance(item, dict) else None)
        for item in recent_diagnostics
    }
    tested_signatures.update(_state_tested_signatures(state))
    if experiment_plan is not None:
        next_action = experiment_plan.get("next_action")
        if isinstance(next_action, dict) and _as_float(next_action.get("score")) >= 0.35:
            patch = next_action.get("config_patch")
            if isinstance(patch, dict):
                signature = _config_signature(patch)
                if signature not in tested_signatures:
                    return {
                        "should_propose": True,
                        "reason": str(next_action.get("action_id") or "profile_driven_candidate"),
                        "diagnosis": str(next_action.get("hypothesis") or "Profile-driven harness candidate."),
                        "config_patch": patch,
                        "expected_effects": [
                            str(item)
                            for item in next_action.get("expected_effects", [])
                            if isinstance(item, str)
                        ],
                        "candidate_score": next_action.get("score"),
                        "bottleneck_hypotheses": experiment_plan.get("bottleneck_hypotheses", []),
                    }
    baseline = recent_diagnostics[0] if recent_diagnostics else {}
    topology_frontier = _topology_frontier_proposal(
        study,
        window_summary,
        state,
        recent_diagnostics,
        tested_signatures=tested_signatures,
    )
    if topology_frontier["should_propose"]:
        return topology_frontier
    runtime_refinement = _runtime_refinement_proposal(
        study,
        window_summary,
        state,
        recent_diagnostics,
        tested_signatures=tested_signatures,
    )
    if runtime_refinement["should_propose"]:
        return runtime_refinement
    if len(state.trials) != 1 or len(recent_diagnostics) != 1:
        return default
    if baseline.get("status") != "completed":
        return default
    if not isinstance(baseline.get("best_request_rate_per_gpu"), (int, float)):
        return default
    active_bottleneck = str(baseline.get("active_bottleneck") or "")
    if active_bottleneck not in {"ttft_prefill", "decode_tpot"}:
        return {
            **default,
            "reason": "baseline_bottleneck_does_not_require_tp_first_probe",
            "diagnosis": f"Baseline bottleneck is {active_bottleneck or 'unknown'}.",
        }
    if "tensor-parallel-size" not in set(study.engine.tunable_flags):
        return {
            **default,
            "reason": "tensor_parallel_size_not_tunable",
        }
    base_flags = dict(study.engine.base_flags)
    baseline_patch = baseline.get("config_patch")
    if isinstance(baseline_patch, dict) and isinstance(baseline_patch.get("flag_patch"), dict):
        base_flags.update(baseline_patch["flag_patch"])
    current_tp = _parse_int_like(base_flags.get("tensor-parallel-size", 1), default=1)
    current_dp = _parse_int_like(base_flags.get("data-parallel-size", 1), default=1)
    next_tp = _next_allowed_tp(study, current_tp=current_tp, current_dp=current_dp)
    if next_tp is None:
        return {
            **default,
            "reason": "no_legal_adjacent_tensor_parallel_probe",
        }
    flag_patch: dict[str, Any] = {"tensor-parallel-size": next_tp}
    signature = _config_signature({"env_patch": {}, "flag_patch": flag_patch})
    if signature in tested_signatures:
        return {
            **default,
            "reason": "adjacent_tensor_parallel_probe_already_tested",
        }
    return {
        "should_propose": True,
        "reason": "first_adjacent_tensor_parallel_probe_for_latency_bottleneck",
        "diagnosis": (
            f"Baseline high-load probes indicate {active_bottleneck}; the generic "
            "topology harness validates the adjacent legal TP increase before "
            "runtime-only or DP/EP probes."
        ),
        "config_patch": {"env_patch": {}, "flag_patch": flag_patch},
        "expected_effects": [
            "reduce per-request latency pressure at higher offered load",
            "validate the nearest TP topology before broader runtime search",
        ],
        "baseline_trial_id": baseline.get("trial_id"),
        "active_bottleneck": active_bottleneck,
    }


def _topology_frontier_proposal(
    study: StudySpec,
    window_summary: dict[str, Any],
    state: StudyState,
    recent_diagnostics: list[dict[str, Any]],
    *,
    tested_signatures: set[str],
) -> dict[str, Any]:
    default = {
        "should_propose": False,
        "reason": "topology_frontier_not_applicable",
        "diagnosis": "No untested topology frontier is justified by the current SLO/workload profile.",
        "config_patch": {"env_patch": {}, "flag_patch": {}},
        "expected_effects": [],
    }
    frontier = _topology_frontier_status(study, state, recent_diagnostics, window_summary)
    if not frontier["frontier_open"]:
        return {**default, "reason": frontier["reason"]}
    flag_patch = frontier.get("flag_patch")
    if not isinstance(flag_patch, dict):
        return {**default, "reason": "topology_frontier_patch_missing"}
    signature = _config_signature({"env_patch": {}, "flag_patch": flag_patch})
    if signature in tested_signatures:
        return {**default, "reason": "topology_frontier_already_tested"}
    return {
        "should_propose": True,
        "reason": "topology_frontier_probe_for_slo_pressure",
        "diagnosis": (
            "The current SLO/workload profile still shows latency pressure and a higher "
            "legal TP frontier has not been measured. Validate that topology before "
            "declaring the incumbent converged or spending more trials on local runtime knobs."
        ),
        "config_patch": {"env_patch": {}, "flag_patch": flag_patch},
        "expected_effects": [
            "test whether extra model parallelism improves the configured TTFT/TPOT pass rate",
            "cover the next legal topology frontier before local runtime refinement",
            "avoid overfitting the harness to the first strong incumbent",
        ],
        "frontier": frontier,
    }


def _experiment_plan(
    study: StudySpec,
    window_summary: dict[str, Any],
    state: StudyState,
    recent_diagnostics: list[dict[str, Any]],
    trial_profiles: list[dict[str, Any]],
    bottleneck_hypotheses: list[dict[str, Any]],
) -> dict[str, Any]:
    tested_signatures = {
        _config_signature(item.get("config_patch") if isinstance(item, dict) else None)
        for item in recent_diagnostics
    }
    tested_signatures.update(_state_tested_signatures(state))
    candidates = _candidate_actions(
        study,
        window_summary,
        state,
        recent_diagnostics,
        trial_profiles,
        bottleneck_hypotheses,
        tested_signatures=tested_signatures,
    )
    candidates.sort(key=lambda item: _as_float(item.get("score")), reverse=True)
    next_action = candidates[0] if candidates else None
    return {
        "planner_version": "profile-driven-v1",
        "bottleneck_hypotheses": bottleneck_hypotheses,
        "candidate_actions": candidates[:8],
        "next_action": next_action,
        "stop_ready": next_action is None or _as_float(next_action.get("score")) < 0.35,
        "stop_rationale": (
            "no untested high-value candidate remains"
            if not candidates or _as_float(candidates[0].get("score")) < 0.35
            else "continue with the highest-scoring measured hypothesis"
        ),
    }


def _candidate_actions(
    study: StudySpec,
    window_summary: dict[str, Any],
    state: StudyState,
    recent_diagnostics: list[dict[str, Any]],
    trial_profiles: list[dict[str, Any]],
    bottleneck_hypotheses: list[dict[str, Any]],
    *,
    tested_signatures: set[str],
) -> list[dict[str, Any]]:
    if not recent_diagnostics:
        return []
    anchor = _anchor_profile(study, state, recent_diagnostics, trial_profiles)
    if anchor is None:
        return []
    top_bottleneck = (
        str(bottleneck_hypotheses[0]["name"])
        if bottleneck_hypotheses
        else str(anchor.get("probe_profile", {}).get("active_bottleneck") or "")
    )
    candidates: list[dict[str, Any]] = []
    candidates.extend(
        _topology_candidate_actions(
            study,
            anchor,
            top_bottleneck,
            bottleneck_hypotheses,
            tested_signatures,
        )
    )
    candidates.extend(
        _runtime_candidate_actions(
            study,
            window_summary,
            anchor,
            top_bottleneck,
            bottleneck_hypotheses,
            tested_signatures,
        )
    )
    return candidates


def _anchor_profile(
    study: StudySpec,
    state: StudyState,
    recent_diagnostics: list[dict[str, Any]],
    trial_profiles: list[dict[str, Any]],
) -> dict[str, Any] | None:
    if state.best_trial_id:
        for profile in reversed(trial_profiles):
            if profile.get("trial_id") == state.best_trial_id:
                return profile
    for profile in reversed(trial_profiles):
        if profile.get("status") == "completed":
            return profile
    return trial_profiles[-1] if trial_profiles else None


def _topology_candidate_actions(
    study: StudySpec,
    anchor: dict[str, Any],
    top_bottleneck: str,
    bottleneck_hypotheses: list[dict[str, Any]],
    tested_signatures: set[str],
) -> list[dict[str, Any]]:
    if not ({"tensor-parallel-size", "data-parallel-size"} & set(study.engine.tunable_flags)):
        return []
    anchor_flags = _effective_flags_for_item(study, anchor)
    current_tp = _parse_int_like(anchor_flags.get("tensor-parallel-size"), default=1)
    current_dp = _parse_int_like(anchor_flags.get("data-parallel-size"), default=1)
    current_ep = _parse_int_like(anchor_flags.get("expert-parallel-size"), default=1)
    current_enable_ep = bool(anchor_flags.get("enable-expert-parallel", False))
    legal = _legal_topology_points(
        study,
        current_tp=current_tp,
        current_dp=current_dp,
        current_ep=current_ep,
        current_enable_ep=current_enable_ep,
    )
    actions: list[dict[str, Any]] = []
    for point in legal:
        if point["tensor-parallel-size"] == current_tp and point["data-parallel-size"] == current_dp:
            continue
        patch = _topology_patch(study, point)
        signature = _config_signature({"env_patch": {}, "flag_patch": patch})
        if signature in tested_signatures:
            continue
        score, factors = _score_topology_candidate(
            top_bottleneck,
            bottleneck_hypotheses,
            request_mode=study.trace.request_mode,
            current_tp=current_tp,
            current_dp=current_dp,
            candidate_tp=point["tensor-parallel-size"],
            candidate_dp=point["data-parallel-size"],
        )
        if score <= 0:
            continue
        action_id = _topology_action_id(current_tp, current_dp, point)
        actions.append(
            {
                "action_id": action_id,
                "knob_family": "topology",
                "score": round(score, 4),
                "score_factors": factors,
                "config_patch": {"env_patch": {}, "flag_patch": patch},
                "hypothesis": _topology_hypothesis(
                    top_bottleneck,
                    current_tp=current_tp,
                    current_dp=current_dp,
                    candidate_tp=point["tensor-parallel-size"],
                    candidate_dp=point["data-parallel-size"],
                ),
                "expected_effects": [
                    "measure whether topology changes relieve the ranked bottleneck",
                    "compare request_rate_per_gpu under the configured SLO, not raw throughput alone",
                    "reject this hypothesis if latency improves but per-GPU throughput regresses materially",
                ],
            }
        )
    return actions


def _runtime_candidate_actions(
    study: StudySpec,
    window_summary: dict[str, Any],
    anchor: dict[str, Any],
    top_bottleneck: str,
    bottleneck_hypotheses: list[dict[str, Any]],
    tested_signatures: set[str],
) -> list[dict[str, Any]]:
    tunable = set(study.engine.tunable_flags)
    anchor_flags = _effective_flags_for_item(study, anchor)
    topology_patch = _preserve_topology_patch(study, anchor_flags)
    actions: list[dict[str, Any]] = []

    if "max-num-batched-tokens" in tunable:
        current_mbt = _parse_int_like(anchor_flags.get("max-num-batched-tokens"), default=0)
        mbt_targets: list[tuple[str, int]] = []
        if top_bottleneck == "ttft_prefill":
            target = (
                _initial_mbt_from_window(window_summary)
                if current_mbt <= 0
                else _next_mbt_step(current_mbt)
            )
            if target is not None:
                mbt_targets.append(("raise_mbt", target))
        elif top_bottleneck == "decode_tpot" and current_mbt > 8192:
            mbt_targets.append(("lower_mbt", max(8192, current_mbt // 2)))
        for action_id, target in mbt_targets:
            patch = {**topology_patch, "max-num-batched-tokens": target}
            signature = _config_signature({"env_patch": {}, "flag_patch": patch})
            if signature in tested_signatures:
                continue
            relief = 0.24 if top_bottleneck == "ttft_prefill" else 0.14
            actions.append(
                _runtime_action(
                    action_id=action_id,
                    knob_family="max-num-batched-tokens",
                    score=relief + _information_gain(bottleneck_hypotheses, "runtime"),
                    patch=patch,
                    hypothesis=(
                        "Adjust max-num-batched-tokens to test whether batching, not topology, "
                        "is limiting the active latency objective."
                    ),
                    expected_effects=[
                        "change prefill/decode batching pressure on the incumbent topology",
                        "confirm if the latency knee moves without requiring another topology change",
                    ],
                )
            )

    if "max-num-seqs" in tunable:
        current_mns = _parse_int_like(anchor_flags.get("max-num-seqs"), default=0)
        mns_targets: list[tuple[str, int]] = []
        if top_bottleneck == "admission_or_queueing":
            target = max(8, int(current_mns * 1.5)) if current_mns > 0 else 64
            mns_targets.append(("raise_max_num_seqs", _round_up_to_multiple(target, 8)))
        elif top_bottleneck == "decode_tpot" and current_mns > 8:
            mns_targets.append(("lower_max_num_seqs", max(8, current_mns // 2)))
        for action_id, target in mns_targets:
            patch = {**topology_patch, "max-num-seqs": target}
            signature = _config_signature({"env_patch": {}, "flag_patch": patch})
            if signature in tested_signatures:
                continue
            relief = 0.25 if top_bottleneck in {"decode_tpot", "admission_or_queueing"} else 0.08
            actions.append(
                _runtime_action(
                    action_id=action_id,
                    knob_family="max-num-seqs",
                    score=relief + _information_gain(bottleneck_hypotheses, "runtime"),
                    patch=patch,
                    hypothesis=(
                        "Adjust max-num-seqs to test whether concurrency pressure is the "
                        "limiting factor under the configured SLO."
                    ),
                    expected_effects=[
                        "change decode/admission concurrency on the incumbent topology",
                        "confirm if TPOT or queueing pressure is caused by sequence concurrency",
                    ],
                )
            )

    if "enable-chunked-prefill" in tunable and top_bottleneck == "ttft_prefill":
        current = bool(anchor_flags.get("enable-chunked-prefill", False))
        if not current:
            patch = {**topology_patch, "enable-chunked-prefill": True}
            signature = _config_signature({"env_patch": {}, "flag_patch": patch})
            if signature not in tested_signatures:
                actions.append(
                    _runtime_action(
                        action_id="enable_chunked_prefill",
                        knob_family="enable-chunked-prefill",
                        score=0.2 + _information_gain(bottleneck_hypotheses, "runtime"),
                        patch=patch,
                        hypothesis=(
                            "Enable chunked prefill to test whether long-prefill head-of-line "
                            "blocking is driving TTFT failures."
                        ),
                        expected_effects=[
                            "reduce long-prefill interference for mixed-length chat windows",
                            "reject if chunking overhead worsens request_rate_per_gpu",
                        ],
                    )
                )
    return actions


def _runtime_action(
    *,
    action_id: str,
    knob_family: str,
    score: float,
    patch: dict[str, Any],
    hypothesis: str,
    expected_effects: list[str],
) -> dict[str, Any]:
    return {
        "action_id": action_id,
        "knob_family": knob_family,
        "score": round(score, 4),
        "score_factors": {
            "expected_bottleneck_relief": round(max(score - 0.1, 0.0), 4),
            "information_gain": 0.1,
            "launch_safety": 0.05,
            "regression_risk": 0.05,
        },
        "config_patch": {"env_patch": {}, "flag_patch": patch},
        "hypothesis": hypothesis,
        "expected_effects": expected_effects,
    }


def _legal_topology_points(
    study: StudySpec,
    *,
    current_tp: int,
    current_dp: int,
    current_ep: int,
    current_enable_ep: bool,
) -> list[dict[str, Any]]:
    constraints = study.engine.topology_constraints
    tunable = set(study.engine.tunable_flags)
    effective_gpu_count = _effective_gpu_count(study)
    if constraints is not None and constraints.allowed_tensor_parallel_sizes:
        tp_values = sorted(set(constraints.allowed_tensor_parallel_sizes))
    elif "tensor-parallel-size" in tunable:
        tp_values = [value for value in [1, 2, 4, 8] if value <= effective_gpu_count]
    else:
        tp_values = [current_tp]

    if constraints is not None and constraints.allowed_data_parallel_sizes:
        dp_values = sorted(set(constraints.allowed_data_parallel_sizes))
    elif "data-parallel-size" in tunable:
        dp_values = [value for value in [1, 2, 4, 8] if value <= effective_gpu_count]
    else:
        dp_values = [current_dp]

    if (
        study.trace.request_mode == "decode_only"
        and current_enable_ep
        and current_ep > 1
    ):
        ep_values = [current_ep]
    elif constraints is not None and constraints.allowed_expert_parallel_sizes:
        ep_values = sorted(set(constraints.allowed_expert_parallel_sizes))
    elif "expert-parallel-size" in tunable:
        ep_values = sorted({1, current_ep})
    else:
        ep_values = [current_ep]

    points: list[dict[str, Any]] = []
    for tp in tp_values:
        for dp in dp_values:
            tp_dp_product = tp * dp
            if constraints is not None:
                if (
                    constraints.allowed_tp_dp_products
                    and tp_dp_product not in constraints.allowed_tp_dp_products
                ):
                    continue
                if (
                    constraints.require_tp_dp_product_equals_gpu_count
                    and tp_dp_product != effective_gpu_count
                ):
                    continue
            elif tp_dp_product > effective_gpu_count:
                continue
            if constraints is not None and not constraints.allowed_tp_dp_products:
                if tp_dp_product > effective_gpu_count:
                    continue
            if tp_dp_product > effective_gpu_count:
                continue
            for ep in ep_values:
                enable_ep = current_enable_ep or ep > 1
                if constraints is not None:
                    if constraints.allowed_expert_parallel_sizes and ep not in constraints.allowed_expert_parallel_sizes:
                        continue
                    if constraints.require_ep_size_leq_tp_dp_product and ep > tp_dp_product:
                        continue
                    if constraints.require_ep_size_divides_tp_dp_product and tp_dp_product % ep != 0:
                        continue
                    if (
                        constraints.require_enable_expert_parallel_when_ep_gt_one
                        and ep > 1
                        and not enable_ep
                    ):
                        continue
                points.append(
                    {
                        "tensor-parallel-size": tp,
                        "data-parallel-size": dp,
                        "expert-parallel-size": ep,
                        "enable-expert-parallel": enable_ep,
                    }
                )
    return points


def _topology_patch(study: StudySpec, point: dict[str, Any]) -> dict[str, Any]:
    patch: dict[str, Any] = {}
    tunable = set(study.engine.tunable_flags)
    base = _normalized_topology_flags(study.engine.base_flags)
    for key in (
        "tensor-parallel-size",
        "data-parallel-size",
        "expert-parallel-size",
        "enable-expert-parallel",
    ):
        if key not in tunable:
            continue
        if key in point and point[key] != base.get(key):
            patch[key] = point[key]
    return patch


def _preserve_topology_patch(study: StudySpec, flags: dict[str, Any]) -> dict[str, Any]:
    patch: dict[str, Any] = {}
    tunable = set(study.engine.tunable_flags)
    base = _normalized_topology_flags(study.engine.base_flags)
    normalized = _normalized_topology_flags(flags)
    for key in (
        "tensor-parallel-size",
        "data-parallel-size",
        "expert-parallel-size",
        "enable-expert-parallel",
    ):
        if key not in tunable or key not in normalized:
            continue
        if normalized.get(key) != base.get(key):
            patch[key] = normalized[key]
    return patch


def _normalized_topology_flags(flags: dict[str, Any]) -> dict[str, Any]:
    return {
        "tensor-parallel-size": _parse_int_like(
            flags.get("tensor-parallel-size"),
            default=1,
        ),
        "data-parallel-size": _parse_int_like(
            flags.get("data-parallel-size"),
            default=1,
        ),
        "expert-parallel-size": _parse_int_like(
            flags.get("expert-parallel-size"),
            default=1,
        ),
        "enable-expert-parallel": bool(flags.get("enable-expert-parallel", False)),
    }


def _effective_gpu_count(study: StudySpec) -> int:
    visible = str(study.engine.base_envs.get("CUDA_VISIBLE_DEVICES") or "").strip()
    if not visible:
        return study.hardware.gpu_count
    if visible.lower() in {"none", "void", "-1"}:
        return 0
    devices = [item.strip() for item in visible.split(",") if item.strip()]
    if not devices:
        return study.hardware.gpu_count
    return min(study.hardware.gpu_count, len(devices))


def _score_topology_candidate(
    top_bottleneck: str,
    bottleneck_hypotheses: list[dict[str, Any]],
    *,
    request_mode: str,
    current_tp: int,
    current_dp: int,
    candidate_tp: int,
    candidate_dp: int,
) -> tuple[float, dict[str, float]]:
    tp_delta = candidate_tp - current_tp
    dp_delta = candidate_dp - current_dp
    confidence = _hypothesis_confidence(bottleneck_hypotheses, top_bottleneck)
    relief = 0.0
    if top_bottleneck == "ttft_prefill":
        relief = 0.42 if tp_delta > 0 else 0.05
    elif top_bottleneck == "decode_tpot" and request_mode == "decode_only":
        if dp_delta > 0 and candidate_tp <= current_tp:
            relief = 0.44
        elif dp_delta > 0:
            relief = 0.24
        elif tp_delta > 0 and candidate_dp < current_dp:
            relief = 0.03
        else:
            relief = 0.08
    elif top_bottleneck == "decode_tpot":
        relief = 0.34 if tp_delta > 0 else 0.02
    elif top_bottleneck == "admission_or_queueing":
        relief = 0.34 if dp_delta > 0 else 0.08
    else:
        relief = 0.04
    info_gain = 0.2 if abs(tp_delta) + abs(dp_delta) > 0 else 0.0
    launch_safety = 0.08 if candidate_tp * candidate_dp <= max(current_tp * current_dp, 1) else 0.04
    distance = abs(_log2_ratio(candidate_tp, current_tp)) + abs(_log2_ratio(candidate_dp, current_dp))
    regression_risk = min(0.28, 0.06 * distance)
    score = relief * max(confidence, 0.35) + info_gain + launch_safety - regression_risk
    return score, {
        "expected_bottleneck_relief": round(relief, 4),
        "bottleneck_confidence": round(confidence, 4),
        "information_gain": round(info_gain, 4),
        "launch_safety": round(launch_safety, 4),
        "regression_risk": round(regression_risk, 4),
    }


def _information_gain(bottleneck_hypotheses: list[dict[str, Any]], family: str) -> float:
    if not bottleneck_hypotheses:
        return 0.08
    top_confidence = _as_float(bottleneck_hypotheses[0].get("confidence"))
    uncertainty = max(0.0, 1.0 - top_confidence)
    return 0.08 + min(0.12, uncertainty * 0.12)


def _hypothesis_confidence(
    bottleneck_hypotheses: list[dict[str, Any]],
    name: str,
) -> float:
    for item in bottleneck_hypotheses:
        if item.get("name") == name:
            return _as_float(item.get("confidence"))
    return 0.0


def _topology_action_id(
    current_tp: int,
    current_dp: int,
    point: dict[str, Any],
) -> str:
    candidate_tp = int(point["tensor-parallel-size"])
    candidate_dp = int(point["data-parallel-size"])
    if candidate_tp > current_tp:
        return "topology_frontier_probe_for_slo_pressure"
    if candidate_dp > current_dp:
        return "increase_data_parallel_probe"
    if candidate_tp < current_tp:
        return "decrease_tensor_parallel_probe"
    return "redistribute_topology_probe"


def _topology_hypothesis(
    top_bottleneck: str,
    *,
    current_tp: int,
    current_dp: int,
    candidate_tp: int,
    candidate_dp: int,
) -> str:
    return (
        f"Ranked bottleneck is {top_bottleneck}. Test topology "
        f"TP={candidate_tp}, DP={candidate_dp} against incumbent TP={current_tp}, "
        f"DP={current_dp}; this distinguishes compute-latency relief from "
        "replica/admission effects under the configured SLO."
    )


def _log2_ratio(new: int, old: int) -> float:
    if new <= 0 or old <= 0:
        return 0.0
    ratio = new / old
    steps = 0.0
    while ratio >= 2.0:
        steps += 1.0
        ratio /= 2.0
    while ratio <= 0.5:
        steps += 1.0
        ratio *= 2.0
    return steps


def _topology_frontier_status(
    study: StudySpec,
    state: StudyState,
    recent_diagnostics: list[dict[str, Any]],
    window_summary: dict[str, Any] | None = None,
) -> dict[str, Any]:
    default = {
        "frontier_open": False,
        "reason": "topology_frontier_not_needed",
        "current_trial_id": state.best_trial_id,
        "active_bottleneck": None,
        "current_tp": None,
        "current_dp": None,
        "next_tp": None,
        "flag_patch": None,
    }
    if "tensor-parallel-size" not in set(study.engine.tunable_flags):
        return {**default, "reason": "tensor_parallel_size_not_tunable"}
    if not state.best_trial_id:
        return {**default, "reason": "no_incumbent_for_topology_frontier"}

    best = next(
        (item for item in recent_diagnostics if item.get("trial_id") == state.best_trial_id),
        None,
    )
    if best is None:
        return {**default, "reason": "incumbent_not_in_recent_harness_history"}
    if best.get("status") != "completed":
        return {**default, "reason": "incumbent_not_completed"}
    if not isinstance(best.get("best_request_rate_per_gpu"), (int, float)):
        return {**default, "reason": "incumbent_has_no_feasible_rate"}

    active_bottleneck = str(best.get("active_bottleneck") or "")
    if active_bottleneck in {"unknown", "none_obvious", ""} and recent_diagnostics:
        active_bottleneck = str(recent_diagnostics[-1].get("active_bottleneck") or "")
    if active_bottleneck not in {"ttft_prefill", "decode_tpot"}:
        return {
            **default,
            "reason": "active_bottleneck_does_not_require_tp_frontier",
            "active_bottleneck": active_bottleneck,
        }
    if active_bottleneck == "decode_tpot" and study.trace.request_mode == "decode_only":
        return {
            **default,
            "reason": "decode_tpot_uses_topology_redistribution_not_higher_tp_frontier",
            "active_bottleneck": active_bottleneck,
        }

    flags = _effective_flags_for_item(study, best)
    current_tp = _parse_int_like(flags.get("tensor-parallel-size"), default=1)
    current_dp = _parse_int_like(flags.get("data-parallel-size"), default=1)
    next_tp = _next_allowed_tp(study, current_tp=current_tp, current_dp=current_dp)
    if next_tp is None:
        return {
            **default,
            "reason": "no_legal_higher_tp_frontier",
            "active_bottleneck": active_bottleneck,
            "current_tp": current_tp,
            "current_dp": current_dp,
        }

    flag_patch: dict[str, Any] = {"tensor-parallel-size": next_tp}
    base_dp = _parse_int_like(study.engine.base_flags.get("data-parallel-size"), default=1)
    if current_dp != base_dp:
        flag_patch["data-parallel-size"] = current_dp
    signature = _config_signature({"env_patch": {}, "flag_patch": flag_patch})
    if signature in _state_tested_signatures(state):
        return {
            **default,
            "reason": "higher_tp_frontier_already_tested",
            "active_bottleneck": active_bottleneck,
            "current_tp": current_tp,
            "current_dp": current_dp,
            "next_tp": next_tp,
            "flag_patch": flag_patch,
        }
    return {
        "frontier_open": True,
        "reason": "higher_tp_frontier_unmeasured_under_slo_pressure",
        "current_trial_id": state.best_trial_id,
        "active_bottleneck": active_bottleneck,
        "current_tp": current_tp,
        "current_dp": current_dp,
        "next_tp": next_tp,
        "flag_patch": flag_patch,
    }


def _effective_flags_for_item(study: StudySpec, item: dict[str, Any]) -> dict[str, Any]:
    flags = dict(study.engine.base_flags)
    patch = item.get("config_patch")
    if isinstance(patch, dict) and isinstance(patch.get("flag_patch"), dict):
        flags.update(patch["flag_patch"])
    return flags


def _state_tested_signatures(state: StudyState) -> set[str]:
    return {
        _config_signature(trial.config_patch)
        for trial in state.trials
        if isinstance(trial.config_patch, dict)
    }


def _runtime_refinement_proposal(
    study: StudySpec,
    window_summary: dict[str, Any],
    state: StudyState,
    recent_diagnostics: list[dict[str, Any]],
    *,
    tested_signatures: set[str],
) -> dict[str, Any]:
    default = {
        "should_propose": False,
        "reason": "runtime_refinement_not_applicable",
        "diagnosis": "Runtime refinement does not apply yet.",
        "config_patch": {"env_patch": {}, "flag_patch": {}},
        "expected_effects": [],
    }
    if not state.best_trial_id or not recent_diagnostics:
        return default
    best = next(
        (item for item in recent_diagnostics if item.get("trial_id") == state.best_trial_id),
        None,
    )
    if not best or best.get("status") != "completed":
        return default
    if recent_diagnostics[-1].get("trial_id") != state.best_trial_id:
        return default
    best_patch = best.get("config_patch")
    if not isinstance(best_patch, dict):
        return default
    best_flags = best_patch.get("flag_patch")
    if not isinstance(best_flags, dict):
        best_flags = {}
    best_tp = _parse_int_like(best_flags.get("tensor-parallel-size"), default=1)
    if best_tp <= 1:
        return default
    tunable = set(study.engine.tunable_flags)
    flag_patch: dict[str, Any] = {"tensor-parallel-size": best_tp}
    if "enable-chunked-prefill" in tunable:
        flag_patch["enable-chunked-prefill"] = True
    if "max-num-batched-tokens" not in tunable:
        return default

    current_mbt = _parse_int_like(best_flags.get("max-num-batched-tokens"), default=0)
    if current_mbt <= 0:
        target_mbt = _initial_mbt_from_window(window_summary)
        reason = "same_topology_runtime_seed_after_tp_incumbent"
    else:
        target_mbt = _next_mbt_step(current_mbt)
        reason = "same_topology_mbt_growth_after_feasible_runtime_incumbent"
    if target_mbt is None:
        return {
            **default,
            "reason": "no_larger_mbt_step_available",
        }
    flag_patch["max-num-batched-tokens"] = target_mbt
    signature = _config_signature({"env_patch": {}, "flag_patch": flag_patch})
    if signature in tested_signatures:
        return {
            **default,
            "reason": "same_topology_runtime_probe_already_tested",
        }
    return {
        "should_propose": True,
        "reason": reason,
        "diagnosis": (
            "A TP incumbent improved request_rate_per_gpu; refine batching on the "
            "same topology before trying DP/EP or broad runtime changes."
        ),
        "config_patch": {"env_patch": {}, "flag_patch": flag_patch},
        "expected_effects": [
            "preserve the incumbent topology",
            "increase batching headroom without also raising memory pressure",
        ],
        "incumbent_trial_id": best.get("trial_id"),
    }


def _initial_mbt_from_window(window_summary: dict[str, Any]) -> int:
    prompt_p99 = _as_float(window_summary.get("prompt_tokens_p99"))
    target = max(8192, int(prompt_p99 * 2.0))
    return min(32768, _round_up_to_multiple(target, 1024))


def _next_mbt_step(current_mbt: int) -> int | None:
    if current_mbt >= 32768:
        return None
    return min(32768, _round_up_to_multiple(int(current_mbt * 1.5), 1024))


def _round_up_to_multiple(value: int, multiple: int) -> int:
    return ((max(value, 1) + multiple - 1) // multiple) * multiple


def _next_allowed_tp(study: StudySpec, *, current_tp: int, current_dp: int) -> int | None:
    constraints = study.engine.topology_constraints
    effective_gpu_count = _effective_gpu_count(study)
    if constraints is not None and constraints.allowed_tensor_parallel_sizes:
        candidates = sorted({int(item) for item in constraints.allowed_tensor_parallel_sizes})
    else:
        candidates = [1, 2, 4, 8]
    for candidate in candidates:
        if candidate <= current_tp:
            continue
        tp_dp_product = candidate * current_dp
        if tp_dp_product > effective_gpu_count:
            continue
        if constraints is not None:
            if (
                constraints.allowed_tp_dp_products
                and tp_dp_product not in constraints.allowed_tp_dp_products
            ):
                continue
            if (
                constraints.require_tp_dp_product_equals_gpu_count
                and tp_dp_product != effective_gpu_count
            ):
                continue
        return candidate
    return None


def _search_high_saturation_guard(
    study: StudySpec,
    state: StudyState,
    recent_diagnostics: list[dict[str, Any]],
) -> dict[str, Any]:
    default = {
        "saturated": False,
        "reason": "search_high_not_saturated",
        "summary": "The incumbent has not saturated the configured search high.",
        "incumbent_trial_id": state.best_trial_id,
        "search_high": study.search.high,
        "last_threshold": None,
        "threshold_gap_to_high": None,
    }
    if not state.best_trial_id:
        return default
    incumbent = next(
        (
            item
            for item in recent_diagnostics
            if item.get("trial_id") == state.best_trial_id
        ),
        None,
    )
    if not incumbent:
        return {
            **default,
            "reason": "incumbent_not_in_recent_harness_history",
        }
    probe_summary = incumbent.get("probe_summary")
    if not isinstance(probe_summary, dict):
        return {
            **default,
            "reason": "incumbent_probe_summary_missing",
        }
    last_probe = probe_summary.get("last_probe")
    if not isinstance(last_probe, dict):
        return {
            **default,
            "reason": "incumbent_last_probe_missing",
        }
    last_threshold = _as_float(last_probe.get("threshold"))
    threshold_gap = float(study.search.high) - last_threshold
    binary_probe_resolution = max(
        float(study.search.tolerance),
        (float(study.search.high) - float(study.search.low)) / float(2 ** max(study.search.max_probes, 1)),
    )
    if not last_probe.get("feasible"):
        return {
            **default,
            "reason": "incumbent_last_probe_not_feasible",
            "last_threshold": last_threshold,
            "threshold_gap_to_high": threshold_gap,
        }
    if threshold_gap > binary_probe_resolution + 1e-12:
        return {
            **default,
            "reason": "incumbent_not_close_to_search_high",
            "last_threshold": last_threshold,
            "threshold_gap_to_high": threshold_gap,
            "binary_probe_resolution": binary_probe_resolution,
        }
    return {
        "saturated": True,
        "reason": "search_high_saturated_by_incumbent",
        "summary": (
            "The incumbent's highest measured probe is feasible and is within "
            "the configured binary-search resolution of search.high."
        ),
        "incumbent_trial_id": state.best_trial_id,
        "search_high": study.search.high,
        "last_threshold": last_threshold,
        "threshold_gap_to_high": threshold_gap,
        "binary_probe_resolution": binary_probe_resolution,
    }


def _validation_exhausted_guard(
    state: StudyState,
    recent_diagnostics: list[dict[str, Any]],
) -> dict[str, Any]:
    default = {
        "exhausted": False,
        "reason": "validation_not_exhausted",
        "summary": "Validation probes are not sufficient to stop yet.",
        "incumbent_trial_id": state.best_trial_id,
        "incumbent_gain_vs_baseline": None,
        "validation_trial_ids": [],
        "validation_families": [],
    }
    if not state.best_trial_id or not isinstance(state.best_request_rate_per_gpu, (int, float)):
        return default
    completed = [
        item
        for item in recent_diagnostics
        if item.get("status") == "completed"
        and isinstance(item.get("best_request_rate_per_gpu"), (int, float))
    ]
    if not completed:
        return default
    baseline_rate = _as_float(completed[0].get("best_request_rate_per_gpu"))
    incumbent_rate = _as_float(state.best_request_rate_per_gpu)
    if baseline_rate <= 0 or incumbent_rate <= 0:
        return default
    gain = incumbent_rate / baseline_rate
    if gain < _STRONG_INCUMBENT_MIN_GAIN:
        return {
            **default,
            "reason": "incumbent_gain_not_large_enough_for_validation_stop",
            "incumbent_gain_vs_baseline": gain,
        }

    best_index = next(
        (
            index
            for index, item in enumerate(recent_diagnostics)
            if item.get("trial_id") == state.best_trial_id
        ),
        None,
    )
    if best_index is None:
        return {
            **default,
            "reason": "incumbent_not_in_recent_harness_history",
            "incumbent_gain_vs_baseline": gain,
        }
    after_best = [
        item
        for item in recent_diagnostics[best_index + 1 :]
        if item.get("status") in {"completed", "failed"}
    ]
    if len(after_best) < _MIN_POST_INCUMBENT_VALIDATION_TRIALS:
        return {
            **default,
            "reason": "need_at_least_two_post_incumbent_validation_trials",
            "incumbent_gain_vs_baseline": gain,
            "validation_trial_ids": [str(item.get("trial_id")) for item in after_best],
        }
    if any(isinstance(item.get("best_request_rate_per_gpu"), (int, float)) for item in after_best):
        return {
            **default,
            "reason": "post_incumbent_validation_found_feasible_candidate",
            "incumbent_gain_vs_baseline": gain,
            "validation_trial_ids": [str(item.get("trial_id")) for item in after_best],
        }

    families: set[str] = set()
    for item in after_best:
        families.update(_validation_families(item))
    has_topology = "topology" in families
    has_runtime = bool(families & {"runtime", "max-num-seqs", "max-num-batched-tokens"})
    enough_evidence = (
        len(after_best) >= _VALIDATION_TRIALS_WITHOUT_FAMILY_COVERAGE
        or (has_topology and has_runtime)
    )
    if not enough_evidence:
        return {
            **default,
            "reason": "post_incumbent_validation_has_not_covered_enough_families",
            "incumbent_gain_vs_baseline": gain,
            "validation_trial_ids": [str(item.get("trial_id")) for item in after_best],
            "validation_families": sorted(families),
        }

    return {
        "exhausted": True,
        "reason": "post_incumbent_validation_exhausted",
        "summary": (
            "A strong incumbent was followed by validation probes across nearby "
            "topology/runtime families, and none produced a feasible candidate."
        ),
        "incumbent_trial_id": state.best_trial_id,
        "incumbent_gain_vs_baseline": gain,
        "validation_trial_ids": [str(item.get("trial_id")) for item in after_best],
        "validation_families": sorted(families),
    }


def _validation_families(item: dict[str, Any]) -> set[str]:
    config_patch = item.get("config_patch")
    if not isinstance(config_patch, dict):
        return set()
    flag_patch = config_patch.get("flag_patch")
    if not isinstance(flag_patch, dict):
        return set()
    families: set[str] = set()
    if any(key in flag_patch for key in _TOPOLOGY_KEYS):
        families.add("topology")
    for key in _RUNTIME_KEYS:
        if key in flag_patch:
            families.add("runtime")
            families.add(key)
    if not families and flag_patch:
        families.add("other")
    return families


def _strong_incumbent_guard(
    state: StudyState,
    recent_diagnostics: list[dict[str, Any]],
) -> dict[str, Any]:
    default = {
        "guard_active": False,
        "reason": "no_strong_incumbent_yet",
        "baseline_trial_id": None,
        "baseline_request_rate_per_gpu": None,
        "incumbent_gain_vs_baseline": None,
    }
    if state.best_trial_id is None or state.best_request_rate_per_gpu is None:
        return default
    completed = [
        item
        for item in recent_diagnostics
        if item.get("status") == "completed"
        and isinstance(item.get("best_request_rate_per_gpu"), (int, float))
    ]
    if len(completed) < 2:
        return default
    baseline = completed[0]
    baseline_rate = float(baseline["best_request_rate_per_gpu"])
    incumbent_rate = float(state.best_request_rate_per_gpu)
    if baseline_rate <= 0:
        return default
    gain = incumbent_rate / baseline_rate
    latest = recent_diagnostics[-1] if recent_diagnostics else {}
    if state.best_trial_id == latest.get("trial_id") and gain >= 1.8:
        return {
            "guard_active": True,
            "reason": "incumbent_exceeds_baseline_by_1_8x_and_latest_trial_is_best_enter_validation_phase",
            "baseline_trial_id": baseline.get("trial_id"),
            "baseline_request_rate_per_gpu": baseline_rate,
            "incumbent_gain_vs_baseline": gain,
            "recommended_next_action": (
                "validate_the_incumbent_with_adjacent_topology_or_same_topology_runtime_probes; "
                "do_not_claim_global_optimum_from_the_first_large_gain"
            ),
        }
    return {
        **default,
        "baseline_trial_id": baseline.get("trial_id"),
        "baseline_request_rate_per_gpu": baseline_rate,
        "incumbent_gain_vs_baseline": gain,
        "reason": "need_more_evidence_before_strong_incumbent_stop",
        "recommended_next_action": "continue_harness_guided_search",
    }


def _infeasible_progress_guard(recent_diagnostics: list[dict[str, Any]]) -> dict[str, Any]:
    points = [
        point
        for item in recent_diagnostics
        if (point := _infeasible_progress_point(item)) is not None
    ]
    default = {
        "plateau_detected": False,
        "stop_if_next_probe_repeats_family": False,
        "reason": "insufficient_infeasible_history",
        "blocked_primary_family": None,
        "recommended_next_action": "continue_adjacent_probe_if_a_harness_justifies_it",
        "comparison": None,
    }
    if len(points) < 2:
        return default

    prev, latest = points[-2], points[-1]
    if not _same_threshold(prev["threshold"], latest["threshold"]):
        return {
            **default,
            "reason": "recent_infeasible_trials_used_different_sampling_thresholds",
        }
    family = _changed_primary_family(prev["config_patch"], latest["config_patch"])
    pass_rate_delta = latest["pass_rate"] - prev["pass_rate"]
    p95_delta_ratio = _relative_delta(latest["ttft_p95_ms"], prev["ttft_p95_ms"])
    p99_delta_ratio = _relative_delta(latest["ttft_p99_ms"], prev["ttft_p99_ms"])
    plateau = (
        family is not None
        and abs(pass_rate_delta) <= 0.01
        and p95_delta_ratio is not None
        and p95_delta_ratio >= -0.02
    )
    comparison = {
        "previous": prev,
        "latest": latest,
        "changed_primary_family": family,
        "pass_rate_delta": pass_rate_delta,
        "ttft_p95_delta_ratio": p95_delta_ratio,
        "ttft_p99_delta_ratio": p99_delta_ratio,
    }
    if not plateau:
        return {
            **default,
            "reason": "recent_infeasible_trials_still_show_material_progress",
            "comparison": comparison,
        }
    return {
        "plateau_detected": True,
        "stop_if_next_probe_repeats_family": True,
        "reason": f"{family}_plateau_on_infeasible_trials",
        "blocked_primary_family": family,
        "recommended_next_action": (
            "switch_primary_family_with_a_specific_bottleneck_rationale_or_return_should_stop"
        ),
        "comparison": comparison,
    }


def _infeasible_progress_point(item: dict[str, Any]) -> dict[str, Any] | None:
    if item.get("status") != "completed" or item.get("best_request_rate") is not None:
        return None
    probe_summary = item.get("probe_summary")
    if not isinstance(probe_summary, dict):
        return None
    probe = probe_summary.get("all_infeasible") or probe_summary.get("last_probe")
    compact = _compact_probe(probe if isinstance(probe, dict) else None)
    if not compact or compact.get("feasible"):
        return None
    latency_summary = compact.get("latency_summary")
    if not isinstance(latency_summary, dict):
        latency_summary = {}
    ttft = latency_summary.get("ttft_ms")
    if not isinstance(ttft, dict):
        ttft = {}
    return {
        "trial_id": item.get("trial_id"),
        "threshold": _as_float(compact.get("threshold")),
        "request_rate": _as_float(compact.get("request_rate")),
        "pass_rate": _as_float(compact.get("pass_rate")),
        "ttft_p95_ms": _optional_float(ttft.get("p95")),
        "ttft_p99_ms": _optional_float(ttft.get("p99")),
        "active_bottleneck": item.get("active_bottleneck"),
        "config_patch": item.get("config_patch") if isinstance(item.get("config_patch"), dict) else {},
    }


def _changed_primary_family(
    previous_patch: dict[str, Any],
    latest_patch: dict[str, Any],
) -> str | None:
    previous_flags = previous_patch.get("flag_patch") if isinstance(previous_patch, dict) else {}
    latest_flags = latest_patch.get("flag_patch") if isinstance(latest_patch, dict) else {}
    if not isinstance(previous_flags, dict) or not isinstance(latest_flags, dict):
        return None
    changed: list[str] = []
    for key, family in (
        ("tensor-parallel-size", "tensor-parallel-size"),
        ("data-parallel-size", "data-parallel-size"),
        ("expert-parallel-size", "expert-parallel-size"),
        ("max-num-seqs", "max-num-seqs"),
        ("max-num-batched-tokens", "max-num-batched-tokens"),
        ("gpu-memory-utilization", "gpu-memory-utilization"),
        ("enable-chunked-prefill", "enable-chunked-prefill"),
    ):
        if previous_flags.get(key) != latest_flags.get(key):
            changed.append(family)
    if len(changed) == 1:
        return changed[0]
    if changed:
        return "mixed:" + ",".join(changed)
    return None


def _same_threshold(left: float, right: float) -> bool:
    return abs(left - right) <= max(abs(left), abs(right), 1.0) * 1e-6


def _relative_delta(new: float | None, old: float | None) -> float | None:
    if new is None or old is None or old <= 0:
        return None
    return (new - old) / old


def _proposal_rules() -> list[str]:
    return [
        "First decide the active bottleneck from recent_trial_diagnostics.",
        "For decode_only studies, ignore TTFT unless a TTFT SLO is explicitly configured; prioritize TPOT pass rate and request_rate_per_gpu.",
        "For decode_tpot bottlenecks, prefer legal TP/DP topology redistribution before runtime-only knobs, then tune max-num-seqs or max-num-batched-tokens only from observed SLO headroom/failures.",
        "Pick at most one primary knob family from knob_harnesses unless the history proves a coupled change is needed.",
        "Use adjacent legal values around the incumbent; avoid broad exploratory jumps.",
        "config_patch is applied to the study base config, not as a delta on the incumbent; when validating an incumbent topology, include all topology flags needed to reconstruct that incumbent plus the runtime knob under test.",
        "When strong_incumbent.guard_active is true, treat the run as a validation phase, not as proof of optimum: probe only adjacent topology or same-topology runtime knobs that can falsify the incumbent.",
        "Do not stop solely because a strong incumbent appeared; stop only after nearby validation probes are exhausted, blocked by infeasible evidence, or repeatedly remain near the incumbent.",
        "During validation, prefer probes that answer whether the incumbent is locally optimal over probes that merely chase another large gain.",
        "Do not enable expert parallel for TTFT-prefill bottlenecks unless expert-parallel is the active harness and there is direct positive EP evidence.",
        "If infeasible_progress blocks the last primary knob family, do not continue that family; switch families with direct bottleneck evidence or set should_stop=true.",
        "If a proposed config is likely to reduce request_rate_per_gpu under the active guard, set should_stop=true instead of exploring.",
        "Never repeat an already tested config signature.",
        "Return should_stop=true when the convergence guard fires and no active harness justifies another adjacent probe.",
    ]


def _workload_default_bottleneck(study: StudySpec, window_summary: dict[str, Any]) -> str:
    if study.trace.request_mode == "decode_only":
        if study.slo.tpot_rule is not None:
            return "decode_tpot"
        if study.slo.ttft_rule is not None:
            return "ttft_prefill"
        return "admission_or_queueing"
    tail_ratio = _as_float(window_summary.get("prompt_tail_ratio_p95_p50"))
    prompt_p95 = _as_float(window_summary.get("prompt_tokens_p95"))
    prefix_cache = window_summary.get("prefix_cache")
    cache_ratio = 0.0
    if isinstance(prefix_cache, dict):
        cache_ratio = _as_float(prefix_cache.get("repeated_token_ratio_estimate"))
    if prompt_p95 >= 4096 or tail_ratio >= 2.0:
        return "ttft_prefill"
    if cache_ratio >= 0.25:
        return "admission_or_queueing"
    return "unknown"


def _length_regime(prompt_p95: float, tail_ratio: float) -> str:
    if prompt_p95 >= 8192 or tail_ratio >= 4.0:
        return "heavy_tail_long_prefill"
    if prompt_p95 >= 4096 or tail_ratio >= 2.0:
        return "moderate_tail_prefill_sensitive"
    return "short_or_moderate"


def _cache_regime(repeated_token_ratio: float) -> str:
    if repeated_token_ratio >= 0.5:
        return "high_prefix_reuse"
    if repeated_token_ratio >= 0.2:
        return "moderate_prefix_reuse"
    return "low_prefix_reuse"


def _arrival_regime(burst_ratio: float, interarrival_cv: float) -> str:
    if burst_ratio >= 3.0 or interarrival_cv >= 2.0:
        return "bursty"
    if burst_ratio >= 1.5 or interarrival_cv >= 1.0:
        return "moderately_bursty"
    return "smooth"


def _as_float(value: Any) -> float:
    if isinstance(value, bool):
        return 0.0
    if isinstance(value, (int, float)):
        return float(value)
    return 0.0


def _optional_float(value: Any) -> float | None:
    if isinstance(value, bool):
        return None
    if isinstance(value, (int, float)):
        return float(value)
    return None


def _parse_int_like(value: Any, *, default: int) -> int:
    if value is None:
        return default
    if isinstance(value, bool):
        return default
    if isinstance(value, int):
        return value
    if isinstance(value, float) and value.is_integer():
        return int(value)
    if isinstance(value, str) and value.strip():
        try:
            return int(value.strip())
        except ValueError:
            return default
    return default


def _config_signature(config_patch: Any) -> str:
    if not isinstance(config_patch, dict):
        config_patch = {}
    env_patch = config_patch.get("env_patch")
    flag_patch = config_patch.get("flag_patch")
    payload = {
        "env_patch": env_patch if isinstance(env_patch, dict) else {},
        "flag_patch": flag_patch if isinstance(flag_patch, dict) else {},
    }
    return json.dumps(payload, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
