Sync from GitHub (tests passed)

app/quality_gate.py

@@ -21,12 +21,16 @@ def evaluate_quality_gate(
     tail_capture: Optional[float] = None,
     quantile_crossing_rate: Optional[float] = None,
     median_sort_gap_max: Optional[float] = None,
+    pi80_width: Optional[float] = None,
+    pi96_width: Optional[float] = None,
     weekly_directional_accuracy: Optional[float] = None,
     weekly_magnitude_ratio: Optional[float] = None,
     weekly_tail_capture_rate: Optional[float] = None,
     weekly_pi80_coverage: Optional[float] = None,
+    weekly_pi80_width: Optional[float] = None,
     weekly_pi80_width_ratio: Optional[float] = None,
     weekly_pi96_coverage: Optional[float] = None,
+    weekly_pi96_width: Optional[float] = None,
     weekly_pi96_width_ratio: Optional[float] = None,
     weekly_quantile_crossing_rate: Optional[float] = None,
     weekly_sorted_quantile_crossing_rate: Optional[float] = None,
@@ -74,6 +78,8 @@ def evaluate_quality_gate(
         reasons.append(
             f"WeeklyPI80Overwide={weekly_pi80_width_ratio:.4f} with coverage={weekly_pi80_coverage:.4f}"
         )
+    if weekly_pi80_width is not None and weekly_pi80_width < 0.0:
+        reasons.append(f"WeeklyPI80Width={weekly_pi80_width:.4f} < 0.0")
 
     if weekly_pi96_coverage is None:
         reasons.append("Missing weekly_pi96_coverage")
@@ -82,33 +88,63 @@ def evaluate_quality_gate(
         reasons.append("Missing weekly_pi96_width_ratio")
     elif weekly_pi96_width_ratio > 3.0:
         reasons.append(f"WeeklyPI96WidthRatio={weekly_pi96_width_ratio:.4f} > 3.0")
+    if weekly_pi96_width is not None and weekly_pi96_width < 0.0:
+        reasons.append(f"WeeklyPI96Width={weekly_pi96_width:.4f} < 0.0")
 
     if weekly_quantile_crossing_rate is None:
         reasons.append("Missing weekly_quantile_crossing_rate")
-    elif weekly_quantile_crossing_rate > 0.05:
-        reasons.append(f"WeeklyQuantileCrossing={weekly_quantile_crossing_rate:.4f} > 0.05")
+    elif weekly_quantile_crossing_rate > 0.001:
+        raise AssertionError(
+            f"WeeklyPublicQuantileCrossing={weekly_quantile_crossing_rate:.4f} > 0.001"
+        )
 
     if weekly_sorted_quantile_crossing_rate is None:
         reasons.append("Missing weekly_sorted_quantile_crossing_rate")
-    elif weekly_sorted_quantile_crossing_rate > 0.0:
-        reasons.append(
-            f"WeeklySortedQuantileCrossing={weekly_sorted_quantile_crossing_rate:.4f} > 0.0"
+    elif weekly_sorted_quantile_crossing_rate > 0.001:
+        raise AssertionError(
+            f"WeeklyOrderedQuantileCrossing={weekly_sorted_quantile_crossing_rate:.4f} > 0.001"
         )
 
-    if weekly_median_sort_gap_max is not None and weekly_median_sort_gap_max > 0.005:
-        reasons.append(f"WeeklyMedianSortGapMax={weekly_median_sort_gap_max:.4f} > 0.005")
+    if weekly_median_sort_gap_max is not None and weekly_median_sort_gap_max > 0.001:
+        raise AssertionError(
+            f"WeeklyOrderedMedianSortGapMax={weekly_median_sort_gap_max:.4f} > 0.001"
+        )
 
     if sharpe < -0.30:
         reasons.append(f"Sharpe={sharpe:.4f} < -0.30")
-    if vr < 0.2 or vr > 3.0:
-        reasons.append(f"VR={vr:.4f} outside [0.2, 3.0]")
     if tail_capture is not None and tail_capture < 0.35:
         reasons.append(f"TailCapture={tail_capture:.4f} < 0.35")
     if quantile_crossing_rate is None:
         reasons.append("Missing quantile_crossing_rate")
-    elif quantile_crossing_rate > 0.20:
-        reasons.append(f"QuantileCrossing={quantile_crossing_rate:.4f} > 0.20")
-    if median_sort_gap_max is not None and median_sort_gap_max > 0.01:
-        reasons.append(f"MedianSortGapMax={median_sort_gap_max:.4f} > 0.01")
+    elif quantile_crossing_rate > 0.001:
+        raise AssertionError(f"PublicQuantileCrossing={quantile_crossing_rate:.4f} > 0.001")
+    if median_sort_gap_max is not None and median_sort_gap_max > 0.001:
+        raise AssertionError(f"OrderedMedianSortGapMax={median_sort_gap_max:.4f} > 0.001")
+    if pi80_width is not None and pi80_width < 0.0:
+        reasons.append(f"PI80Width={pi80_width:.4f} < 0.0")
+    if pi96_width is not None and pi96_width < 0.0:
+        reasons.append(f"PI96Width={pi96_width:.4f} < 0.0")
 
     return len(reasons) == 0, reasons
+
+
+def evaluate_quality_gate_warnings(
+    vr: float,
+    mae_vs_naive_zero: Optional[float] = None,
+    weekly_mae_vs_naive_zero: Optional[float] = None,
+) -> List[str]:
+    """Return stabilization warnings that do not fail promotion yet."""
+    warnings: list[str] = []
+    if vr > 2.5:
+        warnings.append(f"VR={vr:.4f} > 2.5 - model overdispersed")
+    if vr < 0.4:
+        warnings.append(f"VR={vr:.4f} < 0.4 - model underdispersed")
+    if mae_vs_naive_zero is not None and mae_vs_naive_zero > 1.25:
+        warnings.append(
+            f"MAEvsNaiveZero={mae_vs_naive_zero:.4f} > 1.25 - worse than warning baseline"
+        )
+    if weekly_mae_vs_naive_zero is not None and weekly_mae_vs_naive_zero > 1.25:
+        warnings.append(
+            f"WeeklyMAEvsNaiveZero={weekly_mae_vs_naive_zero:.4f} > 1.25 - worse than warning baseline"
+        )
+    return warnings

deep_learning/config.py

@@ -136,15 +136,10 @@ class ASROConfig:
 
 @dataclass(frozen=True)
 class WeeklyLossConfig:
-    lambda_weekly_quantile: float = 0.60
-    lambda_t1_quantile: float = 0.10
+    lambda_weekly_quantile: float = 0.55
+    lambda_t1_quantile: float = 0.15
+    lambda_dispersion: float = 0.20
     lambda_directional: float = 0.10
-    lambda_magnitude: float = 0.55
-    lambda_vol: float = 0.35
-    lambda_crossing: float = 7.0
-    lambda_sanity: float = 0.20
-    lambda_width: float = 0.50
-    lambda_tail_width: float = 0.30
 
 
 @dataclass(frozen=True)

deep_learning/models/hub.py

@@ -48,6 +48,108 @@ def _sha256_file(path: Path) -> str:
     return digest.hexdigest()
 
 
+def _load_json(path: Path) -> dict:
+    if not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except Exception as exc:
+        logger.warning("Could not read JSON artifact %s: %s", path, exc)
+        return {}
+
+
+def build_artifact_health(local_dir: str | Path) -> dict:
+    """Build promotion/inference health metadata for the TFT artifact set."""
+    local_dir = Path(local_dir)
+    metadata_path = local_dir / "tft_metadata.json"
+    checkpoint_present = (local_dir / "best_tft_asro.ckpt").exists()
+    metadata_present = metadata_path.exists()
+    conformal_present = (local_dir / "conformal_calibration.json").exists()
+
+    metadata = _load_json(metadata_path)
+    config = metadata.get("config") or {}
+    metrics = metadata.get("test_metrics") or {}
+    optuna = _load_json(local_dir / "optuna_results.json")
+    structural_report = optuna.get("structural_invalidity_report") or {}
+    best_preflight = optuna.get("best_trial_preflight") or {}
+
+    quality_gate_passed = False
+    gate_error = None
+    if metrics:
+        try:
+            from app.quality_gate import evaluate_quality_gate
+
+            quality_gate_passed, reasons = evaluate_quality_gate(
+                da=float(metrics.get("directional_accuracy", 0.5)),
+                sharpe=float(metrics.get("sharpe_ratio", 0.0)),
+                vr=float(metrics.get("variance_ratio", 1.0)),
+                tail_capture=metrics.get("tail_capture_rate"),
+                quantile_crossing_rate=metrics.get("quantile_crossing_rate"),
+                median_sort_gap_max=metrics.get("median_sort_gap_max"),
+                pi80_width=metrics.get("pi80_width"),
+                pi96_width=metrics.get("pi96_width"),
+                weekly_directional_accuracy=metrics.get("weekly_directional_accuracy"),
+                weekly_magnitude_ratio=metrics.get("weekly_magnitude_ratio"),
+                weekly_tail_capture_rate=metrics.get("weekly_tail_capture_rate"),
+                weekly_pi80_coverage=metrics.get("weekly_pi80_coverage"),
+                weekly_pi80_width=metrics.get("weekly_pi80_width"),
+                weekly_pi80_width_ratio=metrics.get("weekly_pi80_width_ratio"),
+                weekly_pi96_coverage=metrics.get("weekly_pi96_coverage"),
+                weekly_pi96_width=metrics.get("weekly_pi96_width"),
+                weekly_pi96_width_ratio=metrics.get("weekly_pi96_width_ratio"),
+                weekly_quantile_crossing_rate=metrics.get("weekly_quantile_crossing_rate"),
+                weekly_sorted_quantile_crossing_rate=metrics.get(
+                    "weekly_sorted_quantile_crossing_rate"
+                ),
+                weekly_median_sort_gap_max=metrics.get("weekly_median_sort_gap_max"),
+                weekly_sample_count=metrics.get("weekly_sample_count"),
+            )
+            if not quality_gate_passed:
+                gate_error = "; ".join(reasons)
+        except Exception as exc:
+            gate_error = str(exc)
+            quality_gate_passed = False
+    else:
+        gate_error = "missing test_metrics"
+
+    safe = bool(quality_gate_passed and checkpoint_present and metadata_present)
+    next_required_action = "No action required; artifact is promotable."
+    if not safe:
+        next_required_action = (
+            gate_error
+            or "Run deterministic validation and pass the weekly quality gate before upload."
+        )
+
+    return {
+        "forecast_contract_version": (
+            metadata.get("forecast_contract_version")
+            or config.get("forecast_contract_version")
+        ),
+        "monotonic_quantile_transform": bool(
+            config.get("monotonic_quantile_transform")
+            or metadata.get("monotonic_quantile_transform")
+        ),
+        "checkpoint_present": checkpoint_present,
+        "metadata_present": metadata_present,
+        "conformal_present": conformal_present,
+        "quality_gate_passed": quality_gate_passed,
+        "best_trial_preflight_passed": bool(best_preflight.get("preflight_passed", False)),
+        "structural_invalidity_verdict": structural_report.get("verdict", "UNKNOWN"),
+        "safe_to_upload_to_hub": safe,
+        "safe_for_inference": safe,
+        "raw_quantile_crossing_rate": metrics.get("raw_quantile_crossing_rate"),
+        "ordered_quantile_crossing_rate": metrics.get("ordered_quantile_crossing_rate"),
+        "public_quantile_crossing_rate": metrics.get(
+            "public_quantile_crossing_rate",
+            metrics.get("quantile_crossing_rate"),
+        ),
+        "variance_ratio": metrics.get("variance_ratio"),
+        "mae_vs_naive_zero": metrics.get("mae_vs_naive_zero"),
+        "weekly_mae_vs_naive_zero": metrics.get("weekly_mae_vs_naive_zero"),
+        "next_required_action": next_required_action,
+    }
+
+
 def build_artifact_manifest(local_dir: str | Path) -> dict:
     """Build a SHA256 manifest for every present TFT artifact except itself."""
     local_dir = Path(local_dir)
@@ -68,6 +170,7 @@ def build_artifact_manifest(local_dir: str | Path) -> dict:
         "manifest_version": 1,
         "generated_at": datetime.now(timezone.utc).isoformat(),
         "artifacts": artifacts,
+        "artifact_health": build_artifact_health(local_dir),
     }
 
 
@@ -180,6 +283,12 @@ def validate_tft_artifact_set(local_dir: str | Path) -> bool:
     return True
 
 
+def _manifest_safe_to_upload(local_dir: str | Path) -> bool:
+    manifest = _load_json(Path(local_dir) / "artifact_manifest.json")
+    health = manifest.get("artifact_health") or {}
+    return bool(health.get("safe_to_upload_to_hub"))
+
+
 def upload_tft_artifacts(
     local_dir: str | Path,
     repo_id: str,
@@ -208,6 +317,9 @@ def upload_tft_artifacts(
     if not validate_tft_artifact_set(local_dir):
         logger.warning("TFT artifact manifest validation failed before upload")
         return False
+    if not _manifest_safe_to_upload(local_dir):
+        logger.warning("TFT artifact health is not safe for Hub upload; upload skipped")
+        return False
 
     files_to_upload = [
         local_dir / name for name in _ARTIFACTS if (local_dir / name).exists()

deep_learning/models/monotonic_quantiles.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import torch
+import torch.nn.functional as F
+
+
+def enforce_monotonic_quantiles(
+    y_pred: torch.Tensor,
+    median_idx: int = 3,
+    min_gap: float = 1e-5,
+    gap_scale: float = 0.01,
+    init_bias: float = -3.0,
+) -> torch.Tensor:
+    """
+    Transform unconstrained quantile outputs into structurally monotonic
+    quantile outputs.
+
+    The median dimension is preserved exactly. Lower/upper quantile distances
+    are positive by construction and scaled for log-return targets.
+    """
+    base = y_pred[..., median_idx]
+
+    lower_raw = y_pred[..., :median_idx]
+    upper_raw = y_pred[..., median_idx + 1 :]
+
+    lower_steps = min_gap + gap_scale * F.softplus(
+        torch.flip(lower_raw, dims=[-1]) + init_bias
+    )
+    upper_steps = min_gap + gap_scale * F.softplus(upper_raw + init_bias)
+
+    lower_from_median = torch.cumsum(lower_steps, dim=-1)
+    upper_from_median = torch.cumsum(upper_steps, dim=-1)
+
+    lower = base.unsqueeze(-1) - lower_from_median
+    lower = torch.flip(lower, dims=[-1])
+    upper = base.unsqueeze(-1) + upper_from_median
+
+    ordered = torch.cat([lower, base.unsqueeze(-1), upper], dim=-1)
+
+    assert ordered.shape == y_pred.shape, (
+        f"Monotonic transform output shape {ordered.shape} "
+        f"does not match input shape {y_pred.shape}"
+    )
+    return ordered
+
+
+def validate_monotonicity(
+    y_pred: torch.Tensor,
+    tolerance: float = 1e-6,
+) -> dict:
+    """Return crossing diagnostics for an ordered quantile tensor."""
+    diffs = y_pred[..., 1:] - y_pred[..., :-1]
+    violations = diffs < -tolerance
+    crossing_rate = violations.float().mean().item()
+    max_violation = (
+        (-diffs[violations]).max().item() if violations.any().item() else 0.0
+    )
+
+    return {
+        "crossing_rate": crossing_rate,
+        "max_violation": max_violation,
+        "is_valid": crossing_rate == 0.0,
+    }

deep_learning/models/tft_copper.py

@@ -15,10 +15,15 @@ from pathlib import Path
 from typing import Any, Dict, Optional, Sequence
 
 import torch
+import torch.nn.functional as F
 import numpy as np
 
 from deep_learning.contract import RETURN_SPACE, log_to_simple_return
 from deep_learning.config import TFTASROConfig, get_tft_config
+from deep_learning.models.monotonic_quantiles import (
+    enforce_monotonic_quantiles,
+    validate_monotonicity,
+)
 from deep_learning.models.losses import (
     AdaptiveSharpeRatioLoss,
     CombinedQuantileLoss,
@@ -131,38 +136,76 @@ try:
         def __init__(
             self,
             quantiles: list,
-            lambda_weekly_quantile: float = 0.60,
-            lambda_t1_quantile: float = 0.10,
+            lambda_weekly_quantile: float = 0.55,
+            lambda_t1_quantile: float = 0.15,
+            lambda_dispersion: float = 0.20,
             lambda_directional: float = 0.10,
-            lambda_magnitude: float = 0.55,
-            lambda_vol: float = 0.35,
-            lambda_crossing: float = 7.0,
-            lambda_sanity: float = 0.20,
-            lambda_width: float = 0.50,
-            lambda_tail_width: float = 0.30,
-            sharpe_eps: float = 1e-6,
-            daily_log_return_bound: float = 0.08,
-            weekly_log_return_bound: float = 0.20,
+            sharpe_eps: float = 1e-8,
+            debug_mode: bool = False,
         ):
             super().__init__(quantiles=quantiles)
             self.lambda_weekly_quantile = lambda_weekly_quantile
             self.lambda_t1_quantile = lambda_t1_quantile
+            self.lambda_dispersion = lambda_dispersion
             self.lambda_directional = lambda_directional
-            self.lambda_magnitude = lambda_magnitude
-            self.lambda_vol = lambda_vol
-            self.lambda_crossing = lambda_crossing
-            self.lambda_sanity = lambda_sanity
-            self.lambda_width = lambda_width
-            self.lambda_tail_width = lambda_tail_width
             self.sharpe_eps = sharpe_eps
-            self.daily_log_return_bound = daily_log_return_bound
-            self.weekly_log_return_bound = weekly_log_return_bound
+            self.debug_mode = debug_mode
             self.median_idx = len(quantiles) // 2
-            q = list(quantiles)
-            self._q02_idx = q.index(0.02) if 0.02 in q else 0
-            self._q10_idx = q.index(0.10) if 0.10 in q else 1
-            self._q90_idx = q.index(0.90) if 0.90 in q else len(q) - 2
-            self._q98_idx = q.index(0.98) if 0.98 in q else len(q) - 1
+            self.reset_component_accumulators()
+
+        def reset_component_accumulators(self) -> None:
+            self._component_sums = {
+                "weekly_q": 0.0,
+                "t1_q": 0.0,
+                "dispersion": 0.0,
+                "directional": 0.0,
+                "total": 0.0,
+            }
+            self._component_batches = 0
+
+        def _record_components(
+            self,
+            weekly_q_loss: torch.Tensor,
+            t1_q_loss: torch.Tensor,
+            dispersion_loss: torch.Tensor,
+            directional_loss: torch.Tensor,
+            total_loss: torch.Tensor,
+        ) -> None:
+            self._component_sums["weekly_q"] += float(weekly_q_loss.detach().mean().cpu())
+            self._component_sums["t1_q"] += float(t1_q_loss.detach().mean().cpu())
+            self._component_sums["dispersion"] += float(dispersion_loss.detach().mean().cpu())
+            self._component_sums["directional"] += float(directional_loss.detach().mean().cpu())
+            self._component_sums["total"] += float(total_loss.detach().mean().cpu())
+            self._component_batches += 1
+
+        def component_means(self) -> dict:
+            n_batches = self._component_batches
+            if n_batches <= 0:
+                return {
+                    "n_batches": 0,
+                    "weekly_q_loss_mean": 0.0,
+                    "t1_q_loss_mean": 0.0,
+                    "dispersion_loss_mean": 0.0,
+                    "directional_loss_mean": 0.0,
+                    "total_loss_mean": 0.0,
+                    "dominant_component": None,
+                }
+
+            components = {
+                "weekly_q": self._component_sums["weekly_q"],
+                "t1_q": self._component_sums["t1_q"],
+                "dispersion": self._component_sums["dispersion"],
+                "directional": self._component_sums["directional"],
+            }
+            return {
+                "n_batches": n_batches,
+                "weekly_q_loss_mean": self._component_sums["weekly_q"] / n_batches,
+                "t1_q_loss_mean": self._component_sums["t1_q"] / n_batches,
+                "dispersion_loss_mean": self._component_sums["dispersion"] / n_batches,
+                "directional_loss_mean": self._component_sums["directional"] / n_batches,
+                "total_loss_mean": self._component_sums["total"] / n_batches,
+                "dominant_component": max(components, key=components.get),
+            }
 
         def _pinball(self, pred: torch.Tensor, actual: torch.Tensor) -> torch.Tensor:
             q = torch.tensor(self.quantiles, device=pred.device, dtype=pred.dtype).view(1, -1)
@@ -178,70 +221,48 @@ try:
             y_actual = y_actual.float()
             y_pred = y_pred.float()
 
-            median_path = y_pred[..., self.median_idx]
-            pred_weekly_quantiles = y_pred.sum(dim=1)
+            ordered_pred = enforce_monotonic_quantiles(
+                y_pred,
+                median_idx=self.median_idx,
+                min_gap=1e-5,
+                gap_scale=0.01,
+                init_bias=-3.0,
+            )
+            if self.debug_mode:
+                ordered_diagnostics = validate_monotonicity(ordered_pred)
+                assert ordered_diagnostics["is_valid"], (
+                    f"Monotonic transform produced crossings: "
+                    f"rate={ordered_diagnostics['crossing_rate']}, "
+                    f"max_violation={ordered_diagnostics['max_violation']}"
+                )
+                assert torch.allclose(
+                    ordered_pred[..., self.median_idx],
+                    y_pred[..., self.median_idx],
+                    rtol=1e-6,
+                    atol=1e-7,
+                ), "Monotonic transform must preserve the median quantile exactly"
+
+            median_path = ordered_pred[..., self.median_idx]
+            pred_weekly_quantiles = ordered_pred.sum(dim=1)
             actual_weekly = y_actual.sum(dim=1)
 
             weekly_q_loss = self._pinball(pred_weekly_quantiles, actual_weekly)
-            t1_q_loss = super().loss(y_pred[:, 0:1, :], y_actual[:, 0:1])
+            t1_q_loss = super().loss(ordered_pred[:, 0:1, :], y_actual[:, 0:1])
 
             pred_weekly_median = median_path.sum(dim=1)
-            signal = torch.tanh(pred_weekly_median * 20.0)
-            weekly_directional = -(signal * actual_weekly).mean() / (
-                (signal * actual_weekly).std() + self.sharpe_eps
-            )
+            eps = self.sharpe_eps
+            pred_std = pred_weekly_median.std() + eps
+            actual_std = actual_weekly.std() + eps
+            dispersion_loss = torch.abs(torch.log(pred_std / actual_std))
 
-            abs_actual = actual_weekly.abs()
-            material_mask = abs_actual > (abs_actual.median() + self.sharpe_eps)
-            global_magnitude_loss = torch.abs(
-                torch.log(
-                    (pred_weekly_median.abs() + self.sharpe_eps)
-                    / (actual_weekly.abs() + self.sharpe_eps)
-                )
-            ).mean()
-            if material_mask.any():
-                pred_abs = pred_weekly_median[material_mask].abs()
-                true_abs = actual_weekly[material_mask].abs()
-                material_magnitude_loss = torch.abs(
-                    torch.log((pred_abs + self.sharpe_eps) / (true_abs + self.sharpe_eps))
-                ).mean()
-            else:
-                material_magnitude_loss = y_pred.new_tensor(0.0)
-            magnitude_loss = 0.5 * global_magnitude_loss + 0.5 * material_magnitude_loss
+            pred_abs_med = pred_weekly_median.abs().median() + eps
+            actual_abs_med = actual_weekly.abs().median() + eps
+            magnitude_loss = torch.abs(torch.log(pred_abs_med / actual_abs_med))
+            combined_calibration_loss = 0.5 * dispersion_loss + 0.5 * magnitude_loss
 
-            weekly_spread = (
-                pred_weekly_quantiles[:, self._q90_idx]
-                - pred_weekly_quantiles[:, self._q10_idx]
-            )
-            actual_weekly_std = actual_weekly.std() + self.sharpe_eps
-            target_spread = 2.56 * actual_weekly_std
-            mean_weekly_spread = weekly_spread.mean()
-            vol_loss = torch.abs(mean_weekly_spread - target_spread)
-            width_ratio = mean_weekly_spread / (target_spread + self.sharpe_eps)
-            safe_width_ratio = torch.clamp(width_ratio + self.sharpe_eps, min=1e-6)
-            width_loss = torch.abs(torch.log(safe_width_ratio))
-            width_loss = width_loss + torch.relu(width_ratio - 2.0).pow(2)
-
-            weekly_tail_spread = (
-                pred_weekly_quantiles[:, self._q98_idx]
-                - pred_weekly_quantiles[:, self._q02_idx]
-            )
-            target_tail_spread = 4.10 * actual_weekly_std
-            tail_width_ratio = weekly_tail_spread.mean() / (target_tail_spread + self.sharpe_eps)
-            safe_tail_width_ratio = torch.clamp(tail_width_ratio + self.sharpe_eps, min=1e-6)
-            tail_width_loss = torch.abs(torch.log(safe_tail_width_ratio))
-            tail_width_loss = tail_width_loss + torch.relu(tail_width_ratio - 3.0).pow(2)
-            daily_crossing_loss = quantile_crossing_penalty(y_pred)
-            weekly_crossing_loss = quantile_crossing_penalty(pred_weekly_quantiles.unsqueeze(1))
-            crossing_loss = daily_crossing_loss + weekly_crossing_loss
-
-            daily_bound_loss = torch.relu(
-                median_path.abs() - self.daily_log_return_bound
-            ).pow(2).mean()
-            weekly_bound_loss = torch.relu(
-                pred_weekly_median.abs() - self.weekly_log_return_bound
-            ).pow(2).mean()
-            sanity_loss = daily_bound_loss + weekly_bound_loss
+            pred_direction = torch.tanh(median_path * 10.0)
+            actual_direction = torch.sign(y_actual)
+            directional_loss = F.mse_loss(pred_direction, actual_direction.float())
 
             def _to_scalar(x: torch.Tensor) -> torch.Tensor:
                 # pytorch_forecasting metrics can return per-sample tensors;
@@ -249,17 +270,24 @@ try:
                 # boolean comparisons in tests and stable optimizer behaviour.
                 return x.mean() if x.ndim > 0 else x
 
-            return (
+            weekly_q_loss = _to_scalar(weekly_q_loss)
+            t1_q_loss = _to_scalar(t1_q_loss)
+            combined_calibration_loss = _to_scalar(combined_calibration_loss)
+            directional_loss = _to_scalar(directional_loss)
+            total_loss = (
                 self.lambda_weekly_quantile * _to_scalar(weekly_q_loss)
                 + self.lambda_t1_quantile * _to_scalar(t1_q_loss)
-                + self.lambda_directional * _to_scalar(weekly_directional)
-                + self.lambda_magnitude * _to_scalar(magnitude_loss)
-                + self.lambda_vol * _to_scalar(vol_loss)
-                + self.lambda_width * _to_scalar(width_loss)
-                + self.lambda_tail_width * _to_scalar(tail_width_loss)
-                + self.lambda_crossing * _to_scalar(crossing_loss)
-                + self.lambda_sanity * _to_scalar(sanity_loss)
+                + self.lambda_dispersion * _to_scalar(combined_calibration_loss)
+                + self.lambda_directional * _to_scalar(directional_loss)
             )
+            self._record_components(
+                weekly_q_loss,
+                t1_q_loss,
+                combined_calibration_loss,
+                directional_loss,
+                total_loss,
+            )
+            return total_loss
 
 except ImportError:
     ASROPFLoss = None  # type: ignore[assignment,misc]
@@ -295,25 +323,15 @@ def create_tft_model(
             quantiles=quantiles,
             lambda_weekly_quantile=cfg.weekly_loss.lambda_weekly_quantile,
             lambda_t1_quantile=cfg.weekly_loss.lambda_t1_quantile,
+            lambda_dispersion=cfg.weekly_loss.lambda_dispersion,
             lambda_directional=cfg.weekly_loss.lambda_directional,
-            lambda_magnitude=cfg.weekly_loss.lambda_magnitude,
-            lambda_vol=cfg.weekly_loss.lambda_vol,
-            lambda_crossing=cfg.weekly_loss.lambda_crossing,
-            lambda_sanity=cfg.weekly_loss.lambda_sanity,
-            lambda_width=cfg.weekly_loss.lambda_width,
-            lambda_tail_width=cfg.weekly_loss.lambda_tail_width,
         )
         logger.info(
-            "Using weekly ASRO loss | weekly_q=%.2f t1_q=%.2f dir=%.2f mag=%.2f vol=%.2f width=%.2f tail_width=%.2f crossing=%.2f sanity=%.2f",
+            "Using weekly ASRO loss | weekly_q=%.2f t1_q=%.2f dispersion=%.2f dir=%.2f monotonic_transform=true",
             cfg.weekly_loss.lambda_weekly_quantile,
             cfg.weekly_loss.lambda_t1_quantile,
+            cfg.weekly_loss.lambda_dispersion,
             cfg.weekly_loss.lambda_directional,
-            cfg.weekly_loss.lambda_magnitude,
-            cfg.weekly_loss.lambda_vol,
-            cfg.weekly_loss.lambda_width,
-            cfg.weekly_loss.lambda_tail_width,
-            cfg.weekly_loss.lambda_crossing,
-            cfg.weekly_loss.lambda_sanity,
         )
     elif use_asro and ASROPFLoss is not None:
         loss = ASROPFLoss(
@@ -490,20 +508,28 @@ def _format_prediction_legacy_simple_return(
     quantile_diffs = np.diff(raw_pred, axis=-1) if raw_pred.shape[-1] > 1 else np.array([])
     crossing_mask = quantile_diffs < -1e-12 if quantile_diffs.size else np.array([], dtype=bool)
     quantile_crossing_detected = bool(crossing_mask.any())
-    quantile_crossing_rate = float(crossing_mask.mean()) if crossing_mask.size else 0.0
-    sorted_pred = np.sort(raw_pred, axis=-1)
+    raw_quantile_crossing_rate = float(crossing_mask.mean()) if crossing_mask.size else 0.0
+    ordered_tensor = enforce_monotonic_quantiles(
+        torch.as_tensor(raw_pred, dtype=torch.float64),
+        median_idx=median_idx,
+        min_gap=1e-5,
+        gap_scale=0.01,
+        init_bias=-3.0,
+    )
+    pred = ordered_tensor.detach().cpu().numpy()
+    quantile_crossing_rate = 0.0
+    sorted_pred = pred
     median_sort_gap = float(
         np.max(np.abs(raw_pred[..., median_idx] - sorted_pred[..., median_idx]))
     )
     if quantile_crossing_detected:
         logger.error(
             "format_prediction: non-monotonic quantiles detected "
-            "(crossing_rate=%.3f, max_median_sort_gap=%.4f); public output "
-            "will use monotonic sorted quantiles and expose raw_quantiles for audit.",
-            quantile_crossing_rate,
+            "(raw_crossing_rate=%.3f, max_median_sort_gap=%.4f); public output "
+            "uses the structural monotonic transform and exposes raw_quantiles for audit.",
+            raw_quantile_crossing_rate,
             median_sort_gap,
         )
-        pred = sorted_pred
 
     if _math.isnan(baseline_price) or _math.isinf(baseline_price) or baseline_price <= 0:
         logger.warning(
@@ -643,18 +669,42 @@ def format_prediction(
     quantile_diffs = np.diff(raw_pred, axis=-1) if raw_pred.shape[-1] > 1 else np.array([])
     crossing_mask = quantile_diffs < -1e-12 if quantile_diffs.size else np.array([], dtype=bool)
     quantile_crossing_detected = bool(crossing_mask.any())
-    quantile_crossing_rate = float(crossing_mask.mean()) if crossing_mask.size else 0.0
-    sorted_pred = np.sort(raw_pred, axis=-1)
-    median_sort_gap = float(np.max(np.abs(raw_pred[..., median_idx] - sorted_pred[..., median_idx])))
+    raw_quantile_crossing_rate = float(crossing_mask.mean()) if crossing_mask.size else 0.0
+    ordered_tensor = enforce_monotonic_quantiles(
+        torch.as_tensor(raw_pred, dtype=torch.float64),
+        median_idx=median_idx,
+        min_gap=1e-5,
+        gap_scale=0.01,
+        init_bias=-3.0,
+    )
+    pred = ordered_tensor.detach().cpu().numpy()
+    ordered_diffs = np.diff(pred, axis=-1) if pred.shape[-1] > 1 else np.array([])
+    ordered_crossing_mask = (
+        ordered_diffs < -1e-12 if ordered_diffs.size else np.array([], dtype=bool)
+    )
+    ordered_quantile_crossing_rate = (
+        float(ordered_crossing_mask.mean()) if ordered_crossing_mask.size else 0.0
+    )
+    if ordered_quantile_crossing_rate > 0.0:
+        raise AssertionError(
+            "Monotonic quantile transform produced public crossings: "
+            f"{ordered_quantile_crossing_rate:.6f}"
+        )
+    sorted_raw = np.sort(raw_pred, axis=-1)
+    raw_median_sort_gap = float(
+        np.max(np.abs(raw_pred[..., median_idx] - sorted_raw[..., median_idx]))
+    )
+    ordered_median_sort_gap = float(
+        np.max(np.abs(pred[..., median_idx] - np.sort(pred, axis=-1)[..., median_idx]))
+    )
     if quantile_crossing_detected:
         logger.error(
             "format_prediction: non-monotonic quantiles detected "
-            "(crossing_rate=%.3f, max_median_sort_gap=%.4f); public output "
-            "will use monotonic sorted quantiles and expose raw_quantiles for audit.",
-            quantile_crossing_rate,
-            median_sort_gap,
+            "(raw_crossing_rate=%.3f, raw_max_median_sort_gap=%.4f); public output "
+            "uses the structural monotonic transform and exposes raw_quantiles for audit.",
+            raw_quantile_crossing_rate,
+            raw_median_sort_gap,
         )
-        pred = sorted_pred
 
     if _math.isnan(baseline_price) or _math.isinf(baseline_price) or baseline_price <= 0:
         logger.warning(
@@ -750,8 +800,13 @@ def format_prediction(
         "quantiles_log": {f"q{q:.2f}": float(bounded_pred[0, i]) for i, q in enumerate(q_list)},
         "raw_quantiles": {f"q{q:.2f}": float(raw_pred[0, i]) for i, q in enumerate(q_list)},
         "quantile_crossing_detected": quantile_crossing_detected,
-        "quantile_crossing_rate": quantile_crossing_rate,
-        "median_sort_gap": median_sort_gap,
+        "quantile_crossing_rate": ordered_quantile_crossing_rate,
+        "raw_quantile_crossing_rate": raw_quantile_crossing_rate,
+        "ordered_quantile_crossing_rate": ordered_quantile_crossing_rate,
+        "public_quantile_crossing_rate": ordered_quantile_crossing_rate,
+        "median_sort_gap": ordered_median_sort_gap,
+        "raw_median_sort_gap": raw_median_sort_gap,
+        "ordered_median_sort_gap": ordered_median_sort_gap,
         "weekly_return": log_to_simple_return(weekly_log_return),
         "weekly_log_return": weekly_log_return,
         "weekly_price": _price(weekly_log_return),

deep_learning/training/callbacks.py

@@ -81,6 +81,47 @@ class CurriculumLossScheduler(pl.Callback):
             )
 
 
+class WeeklyLossComponentLogger(pl.Callback):
+    """Log weekly loss component scales at validation epoch boundaries."""
+
+    def on_validation_epoch_start(self, trainer, pl_module):
+        loss = getattr(pl_module, "loss", None)
+        if hasattr(loss, "reset_component_accumulators"):
+            loss.reset_component_accumulators()
+
+    def on_validation_epoch_end(self, trainer, pl_module):
+        loss = getattr(pl_module, "loss", None)
+        if not hasattr(loss, "component_means"):
+            return
+
+        stats = loss.component_means()
+        if not stats.get("n_batches"):
+            return
+
+        epoch = getattr(trainer, "current_epoch", 0)
+        logger.info(
+            "Weekly loss components | epoch=%s weekly_q=%.6f t1_q=%.6f "
+            "dispersion=%.6f directional=%.6f total=%.6f dominant=%s",
+            epoch,
+            stats["weekly_q_loss_mean"],
+            stats["t1_q_loss_mean"],
+            stats["dispersion_loss_mean"],
+            stats["directional_loss_mean"],
+            stats["total_loss_mean"],
+            stats["dominant_component"],
+        )
+        if stats["dispersion_loss_mean"] > 3.0 * max(stats["weekly_q_loss_mean"], 1e-12):
+            logger.warning(
+                "Weekly dispersion loss is dominating weekly quantile loss; "
+                "lambda_dispersion may need to be reduced."
+            )
+        if stats["directional_loss_mean"] < 0.05 * max(stats["total_loss_mean"], 1e-12):
+            logger.warning(
+                "Weekly directional loss is below 5%% of total loss; "
+                "lambda_directional may need to increase."
+            )
+
+
 class SWACallback(pl.Callback):
     """
     Stochastic Weight Averaging over the last ``swa_pct`` of training.

deep_learning/training/hyperopt.py

@@ -13,6 +13,7 @@ from __future__ import annotations
 import argparse
 import json
 import logging
+import sys
 import warnings
 from dataclasses import replace
 from pathlib import Path
@@ -37,6 +38,16 @@ from deep_learning.config import (
 )
 from deep_learning.logging_utils import configure_cli_logging, suppress_lightning_noise
 
+PROJECT_ROOT = Path(__file__).resolve().parents[3]
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+from scripts.hyperopt_diagnostics import (
+    best_trial_preflight_check,
+    compute_structural_invalidity_report,
+    compute_trial_distribution_summary,
+)
+
 logger = logging.getLogger(__name__)
 
 MIN_COMPLETED_TRIALS = 10
@@ -55,15 +66,10 @@ KNOWN_GOOD_TRIAL_PARAMS = {
     "lambda_vol": 0.30,
     "lambda_quantile": 0.25,
     "lambda_madl": 0.40,
-    "lambda_weekly_quantile": 0.60,
-    "lambda_t1_quantile": 0.10,
+    "lambda_weekly_quantile": 0.55,
+    "lambda_t1_quantile": 0.15,
+    "lambda_dispersion": 0.20,
     "lambda_directional": 0.10,
-    "lambda_magnitude": 0.55,
-    "weekly_lambda_vol": 0.35,
-    "lambda_width": 0.50,
-    "lambda_tail_width": 0.30,
-    "lambda_sanity": 0.20,
-    "lambda_crossing": 7.0,
     "batch_size": 32,
 }
 
@@ -144,7 +150,9 @@ def _build_prune_diagnostics(study) -> tuple[dict[str, int], list[dict]]:
         "avg_variance_ratio",
         "avg_directional_accuracy",
         "avg_val_sharpe",
+        "avg_raw_quantile_crossing_rate",
         "avg_quantile_crossing_rate",
+        "avg_raw_median_sort_gap",
         "avg_median_sort_gap",
         "avg_weekly_magnitude_ratio",
         "avg_weekly_pi80_coverage",
@@ -180,6 +188,8 @@ def _build_result_payload(study) -> dict:
     trial_state_counts = _trial_state_counts(study)
     best = _best_finite_completed_trial(study)
     prune_reasons, fold_diagnostics = _build_prune_diagnostics(study)
+    structural_report = compute_structural_invalidity_report(fold_diagnostics)
+    distribution_summary = compute_trial_distribution_summary(fold_diagnostics)
 
     if best is None:
         return {
@@ -191,6 +201,9 @@ def _build_result_payload(study) -> dict:
             "trial_state_counts": trial_state_counts,
             "prune_reasons": prune_reasons,
             "fold_diagnostics": fold_diagnostics,
+            "structural_invalidity_report": structural_report,
+            "trial_distribution_summary": distribution_summary,
+            "best_trial_preflight": None,
             "message": (
                 "No Optuna trials completed with a finite objective value; "
                 "final training will use the known-good fallback config "
@@ -198,6 +211,11 @@ def _build_result_payload(study) -> dict:
             ),
         }
 
+    best_diagnostics = next(
+        (d for d in fold_diagnostics if d.get("trial") == best.number),
+        {},
+    )
+    preflight = best_trial_preflight_check(best_diagnostics)
     return {
         "status": "completed",
         "best_trial": best.number,
@@ -207,6 +225,9 @@ def _build_result_payload(study) -> dict:
         "trial_state_counts": trial_state_counts,
         "prune_reasons": prune_reasons,
         "fold_diagnostics": fold_diagnostics,
+        "structural_invalidity_report": structural_report,
+        "trial_distribution_summary": distribution_summary,
+        "best_trial_preflight": preflight,
     }
 
 
@@ -266,15 +287,10 @@ def create_trial_config(trial, base_cfg: TFTASROConfig) -> TFTASROConfig:
     )
 
     weekly_loss_cfg = WeeklyLossConfig(
-        lambda_weekly_quantile=trial.suggest_float("lambda_weekly_quantile", 0.60, 0.75, step=0.05),
-        lambda_t1_quantile=trial.suggest_float("lambda_t1_quantile", 0.05, 0.15, step=0.05),
+        lambda_weekly_quantile=trial.suggest_float("lambda_weekly_quantile", 0.45, 0.65, step=0.05),
+        lambda_t1_quantile=trial.suggest_float("lambda_t1_quantile", 0.05, 0.20, step=0.05),
+        lambda_dispersion=trial.suggest_float("lambda_dispersion", 0.15, 0.35, step=0.05),
         lambda_directional=trial.suggest_float("lambda_directional", 0.05, 0.12, step=0.01),
-        lambda_magnitude=trial.suggest_float("lambda_magnitude", 0.50, 0.80, step=0.05),
-        lambda_vol=trial.suggest_float("weekly_lambda_vol", 0.25, 0.45, step=0.05),
-        lambda_crossing=trial.suggest_float("lambda_crossing", 5.0, 10.0, step=1.0),
-        lambda_sanity=trial.suggest_float("lambda_sanity", 0.10, 0.30, step=0.05),
-        lambda_width=trial.suggest_float("lambda_width", 0.40, 0.90, step=0.05),
-        lambda_tail_width=trial.suggest_float("lambda_tail_width", 0.25, 0.75, step=0.05),
     )
 
     training_cfg = TrainingConfig(
@@ -343,6 +359,7 @@ def _objective(trial, base_cfg: TFTASROConfig, master_data: tuple) -> float:
     from deep_learning.training.callbacks import CurriculumLossScheduler
     from deep_learning.training.metrics import (
         compute_weekly_metrics,
+        monotonic_quantiles_np,
         quantile_crossing_rate,
         quantile_median_sort_gap,
         select_prediction_horizon,
@@ -367,7 +384,9 @@ def _objective(trial, base_cfg: TFTASROConfig, master_data: tuple) -> float:
     fold_sharpe_list: list[float] = []
     fold_vr_list: list[float] = []
     fold_crossing_list: list[float] = []
+    fold_raw_crossing_list: list[float] = []
     fold_median_gap_list: list[float] = []
+    fold_raw_median_gap_list: list[float] = []
     fold_weekly_objectives: list[float] = []
     fold_weekly_mr_list: list[float] = []
     fold_weekly_pi80_coverage_list: list[float] = []
@@ -469,10 +488,14 @@ def _objective(trial, base_cfg: TFTASROConfig, master_data: tuple) -> float:
                 raise ValueError(
                     f"Prediction horizon too short: {pred_np.shape[1]} < {trial_cfg.forecast.primary_horizon_days}"
                 )
-            pred_t1 = pred_np[:, 0, :]
+            ordered_pred_np = monotonic_quantiles_np(pred_np, median_idx=median_idx)
+            raw_pred_t1 = pred_np[:, 0, :]
+            pred_t1 = ordered_pred_np[:, 0, :]
             y_pred = pred_t1[:, median_idx]
             fold_crossing_rate = quantile_crossing_rate(pred_t1)
+            fold_raw_crossing_rate = quantile_crossing_rate(raw_pred_t1)
             _, fold_median_gap = quantile_median_sort_gap(pred_t1, median_idx)
+            _, fold_raw_median_gap = quantile_median_sort_gap(raw_pred_t1, median_idx)
 
             y_actual_parts = []
             for batch in fold_val_dl:
@@ -510,7 +533,7 @@ def _objective(trial, base_cfg: TFTASROConfig, master_data: tuple) -> float:
             )
             weekly_pinball = _weekly_pinball_loss(
                 y_actual_path[:n_path],
-                pred_np[:n_path],
+                ordered_pred_np[:n_path],
                 tuple(trial_cfg.model.quantiles),
                 horizon=trial_cfg.forecast.primary_horizon_days,
             )
@@ -518,9 +541,9 @@ def _objective(trial, base_cfg: TFTASROConfig, master_data: tuple) -> float:
             fold_weekly_pi80_coverage = float(weekly.get("weekly_pi80_coverage", 0.0))
             fold_weekly_pi80_width_ratio = float(weekly.get("weekly_pi80_width_ratio", 1.0))
             fold_weekly_pi96_width_ratio = float(weekly.get("weekly_pi96_width_ratio", 1.0))
-            fold_weekly_raw_crossing = float(weekly.get("weekly_quantile_crossing_rate", 0.0))
+            fold_weekly_raw_crossing = float(weekly.get("weekly_raw_quantile_crossing_rate", 0.0))
             fold_weekly_sorted_crossing = float(
-                weekly.get("weekly_sorted_quantile_crossing_rate", 0.0)
+                weekly.get("weekly_ordered_quantile_crossing_rate", 0.0)
             )
             fold_weekly_interval_score_80 = float(weekly.get("weekly_interval_score_80", 0.0))
             fold_weekly_interval_score_96 = float(weekly.get("weekly_interval_score_96", 0.0))
@@ -530,7 +553,6 @@ def _objective(trial, base_cfg: TFTASROConfig, master_data: tuple) -> float:
             coverage_penalty = abs(fold_weekly_pi80_coverage - 0.80)
             width_penalty = max(0.0, fold_weekly_pi80_width_ratio - 1.5)
             tail_width_penalty = max(0.0, fold_weekly_pi96_width_ratio - 3.0)
-            raw_crossing_penalty = max(0.0, fold_weekly_raw_crossing - 0.05)
             fold_weekly_objective = (
                 0.35 * weekly_pinball
                 + 0.15 * (1.0 - float(weekly.get("weekly_directional_accuracy", 0.5)))
@@ -540,7 +562,6 @@ def _objective(trial, base_cfg: TFTASROConfig, master_data: tuple) -> float:
                 + 0.35 * tail_width_penalty
                 + 0.10 * interval_score_penalty
                 + 0.05 * interval_score_96_penalty
-                + 0.50 * raw_crossing_penalty
                 + 0.25 * fold_weekly_sorted_crossing
             )
         except Exception as exc:
@@ -553,7 +574,9 @@ def _objective(trial, base_cfg: TFTASROConfig, master_data: tuple) -> float:
         fold_da_list.append(fold_da)
         fold_sharpe_list.append(fold_sharpe)
         fold_crossing_list.append(fold_crossing_rate)
+        fold_raw_crossing_list.append(fold_raw_crossing_rate)
         fold_median_gap_list.append(fold_median_gap)
+        fold_raw_median_gap_list.append(fold_raw_median_gap)
         fold_weekly_objectives.append(fold_weekly_objective)
         fold_weekly_mr_list.append(fold_weekly_mr)
         fold_weekly_pi80_coverage_list.append(fold_weekly_pi80_coverage)
@@ -671,7 +694,13 @@ def _objective(trial, base_cfg: TFTASROConfig, master_data: tuple) -> float:
     avg_sharpe = float(np.mean(fold_sharpe_list)) if fold_sharpe_list else 0.0
     avg_vr = float(np.mean(fold_vr_list)) if fold_vr_list else 0.0
     avg_crossing = float(np.mean(fold_crossing_list)) if fold_crossing_list else 0.0
+    avg_raw_crossing = (
+        float(np.mean(fold_raw_crossing_list)) if fold_raw_crossing_list else 0.0
+    )
     avg_median_gap = float(np.mean(fold_median_gap_list)) if fold_median_gap_list else 0.0
+    avg_raw_median_gap = (
+        float(np.mean(fold_raw_median_gap_list)) if fold_raw_median_gap_list else 0.0
+    )
     avg_weekly_mr = float(np.mean(fold_weekly_mr_list)) if fold_weekly_mr_list else 1.0
     avg_weekly_pi80_coverage = (
         float(np.mean(fold_weekly_pi80_coverage_list))
@@ -717,7 +746,9 @@ def _objective(trial, base_cfg: TFTASROConfig, master_data: tuple) -> float:
     trial.set_user_attr("avg_variance_ratio", round(avg_vr, 4))
     trial.set_user_attr("avg_directional_accuracy", round(avg_da, 4))
     trial.set_user_attr("avg_val_sharpe", round(avg_sharpe, 4))
+    trial.set_user_attr("avg_raw_quantile_crossing_rate", round(avg_raw_crossing, 4))
     trial.set_user_attr("avg_quantile_crossing_rate", round(avg_crossing, 4))
+    trial.set_user_attr("avg_raw_median_sort_gap", round(avg_raw_median_gap, 4))
     trial.set_user_attr("avg_median_sort_gap", round(avg_median_gap, 4))
     trial.set_user_attr("avg_weekly_magnitude_ratio", round(avg_weekly_mr, 4))
     trial.set_user_attr("avg_weekly_pi80_coverage", round(avg_weekly_pi80_coverage, 4))
@@ -741,21 +772,11 @@ def _objective(trial, base_cfg: TFTASROConfig, master_data: tuple) -> float:
         trial.set_user_attr("prune_reason", "sharpe_prune")
         raise optuna.exceptions.TrialPruned()
 
-    if (avg_crossing > 0.20 or avg_median_gap > 0.01) and not protect_trial:
-        logger.warning(
-            "Trial %d PRUNED: quantile incoherence crossing=%.3f median_gap=%.4f",
-            trial.number, avg_crossing, avg_median_gap,
-        )
-        trial.set_user_attr("prune_reason", "crossing_prune")
-        raise optuna.exceptions.TrialPruned()
-
-    if (avg_weekly_raw_crossing > 0.05 or avg_weekly_sorted_crossing > 0.0) and not protect_trial:
-        logger.warning(
-            "Trial %d PRUNED: weekly quantile incoherence raw=%.3f sorted=%.3f",
-            trial.number, avg_weekly_raw_crossing, avg_weekly_sorted_crossing,
+    if avg_crossing > 0.001 or avg_weekly_sorted_crossing > 0.001:
+        raise RuntimeError(
+            "Monotonic quantile transform produced public crossings: "
+            f"daily={avg_crossing:.6f}, weekly={avg_weekly_sorted_crossing:.6f}"
         )
-        trial.set_user_attr("prune_reason", "weekly_raw_crossing_prune")
-        raise optuna.exceptions.TrialPruned()
 
     # Soft penalty: avg DA below coin-flip
     da_penalty = 2.0 * max(0.0, 0.50 - avg_da) if avg_da < 0.50 else 0.0
@@ -825,6 +846,15 @@ def run_hyperopt(
     results_path.parent.mkdir(parents=True, exist_ok=True)
     result = _build_result_payload(study)
     results_path.write_text(json.dumps(result, indent=2, allow_nan=False))
+    logger.info(
+        "Optuna structural invalidity report: %s",
+        result.get("structural_invalidity_report"),
+    )
+    logger.info(
+        "Optuna trial distribution summary: %s",
+        result.get("trial_distribution_summary"),
+    )
+    logger.info("Optuna best trial preflight: %s", result.get("best_trial_preflight"))
 
     if result["best_trial"] is None:
         logger.warning(
@@ -841,6 +871,10 @@ def run_hyperopt(
         )
         logger.info("Best params: %s", result["best_params"])
 
+    structural_report = result.get("structural_invalidity_report") or {}
+    if structural_report.get("verdict") == "STRUCTURAL_FAILURE":
+        raise RuntimeError(structural_report.get("next_action", "Structural failure in hyperopt."))
+
     return result
 
 

deep_learning/training/metrics.py

@@ -13,6 +13,9 @@ from __future__ import annotations
 
 import numpy as np
 import pandas as pd
+import torch
+
+from deep_learning.models.monotonic_quantiles import enforce_monotonic_quantiles
 
 
 def select_prediction_horizon(values: np.ndarray, horizon_idx: int = 0) -> np.ndarray:
@@ -53,6 +56,27 @@ def cumulative_quantiles(pred: np.ndarray, horizon: int = 5) -> np.ndarray:
     return arr[:, :horizon, :].sum(axis=1)
 
 
+def monotonic_quantiles_np(
+    pred: np.ndarray,
+    median_idx: int | None = None,
+) -> np.ndarray:
+    """Apply the production monotonic quantile transform to a numpy tensor."""
+    arr = np.asarray(pred, dtype=np.float64)
+    if arr.shape[-1] == 0:
+        return arr.copy()
+    if median_idx is None:
+        median_idx = arr.shape[-1] // 2
+    tensor = torch.as_tensor(arr, dtype=torch.float64)
+    ordered = enforce_monotonic_quantiles(
+        tensor,
+        median_idx=median_idx,
+        min_gap=1e-5,
+        gap_scale=0.01,
+        init_bias=-3.0,
+    )
+    return ordered.detach().cpu().numpy()
+
+
 def magnitude_ratio(y_actual: np.ndarray, y_pred: np.ndarray) -> float:
     """Median predicted absolute move divided by median actual absolute move."""
     denom = np.median(np.abs(np.asarray(y_actual, dtype=np.float64)))
@@ -288,18 +312,24 @@ def compute_all_metrics(
 
     if y_pred_quantiles is not None:
         q_arr = np.asarray(y_pred_quantiles, dtype=np.float64)
-        sorted_q = np.sort(q_arr, axis=-1)
+        ordered_q = monotonic_quantiles_np(q_arr)
         raw_crossing = quantile_crossing_rate(q_arr)
-        sorted_crossing = quantile_crossing_rate(sorted_q)
-        metrics["quantile_crossing_rate"] = raw_crossing
+        ordered_crossing = quantile_crossing_rate(ordered_q)
+        metrics["quantile_crossing_rate"] = ordered_crossing
         metrics["raw_quantile_crossing_rate"] = raw_crossing
-        metrics["sorted_quantile_crossing_rate"] = sorted_crossing
+        metrics["ordered_quantile_crossing_rate"] = ordered_crossing
+        metrics["public_quantile_crossing_rate"] = ordered_crossing
+        metrics["sorted_quantile_crossing_rate"] = ordered_crossing
         gap_mean, gap_max = quantile_median_sort_gap(q_arr)
-        metrics["median_sort_gap_mean"] = gap_mean
-        metrics["median_sort_gap_max"] = gap_max
-        sorted_gap_mean, sorted_gap_max = quantile_median_sort_gap(sorted_q)
-        metrics["sorted_median_sort_gap_mean"] = sorted_gap_mean
-        metrics["sorted_median_sort_gap_max"] = sorted_gap_max
+        metrics["raw_median_sort_gap_mean"] = gap_mean
+        metrics["raw_median_sort_gap_max"] = gap_max
+        ordered_gap_mean, ordered_gap_max = quantile_median_sort_gap(ordered_q)
+        metrics["median_sort_gap_mean"] = ordered_gap_mean
+        metrics["median_sort_gap_max"] = ordered_gap_max
+        metrics["ordered_median_sort_gap_mean"] = ordered_gap_mean
+        metrics["ordered_median_sort_gap_max"] = ordered_gap_max
+        metrics["sorted_median_sort_gap_mean"] = ordered_gap_mean
+        metrics["sorted_median_sort_gap_max"] = ordered_gap_max
 
     return metrics
 
@@ -317,8 +347,10 @@ def compute_weekly_metrics(
     to simple returns happens only during inference formatting.
     """
     weekly_actual = cumulative_horizon(y_actual_path, horizon=horizon)
-    approx_weekly_quantiles = cumulative_quantiles(y_pred_quantiles_path, horizon=horizon)
-    weekly_quantiles = np.sort(approx_weekly_quantiles, axis=-1)
+    raw_path = np.asarray(y_pred_quantiles_path, dtype=np.float64)
+    ordered_path = monotonic_quantiles_np(raw_path, median_idx=len(quantiles) // 2)
+    raw_weekly_quantiles = cumulative_quantiles(raw_path, horizon=horizon)
+    weekly_quantiles = cumulative_quantiles(ordered_path, horizon=horizon)
 
     median_idx = len(quantiles) // 2
     q10_idx = quantiles.index(0.10)
@@ -340,18 +372,27 @@ def compute_weekly_metrics(
         y_pred_q90=weekly_quantiles[:, q90_idx],
         y_pred_q02=weekly_quantiles[:, q02_idx],
         y_pred_q98=weekly_quantiles[:, q98_idx],
-        y_pred_quantiles=approx_weekly_quantiles,
+        y_pred_quantiles=weekly_quantiles,
         tail_threshold=tail_threshold,
     )
 
     weekly_metrics = {f"weekly_{k}": v for k, v in metrics.items()}
     weekly_metrics["weekly_interval_quantile_source"] = 1.0
     weekly_metrics["weekly_approx_quantile_crossing_rate"] = quantile_crossing_rate(
-        approx_weekly_quantiles
+        raw_weekly_quantiles
     )
-    approx_gap_mean, approx_gap_max = quantile_median_sort_gap(approx_weekly_quantiles)
+    approx_gap_mean, approx_gap_max = quantile_median_sort_gap(raw_weekly_quantiles)
     weekly_metrics["weekly_approx_median_sort_gap_mean"] = approx_gap_mean
     weekly_metrics["weekly_approx_median_sort_gap_max"] = approx_gap_max
+    weekly_metrics["weekly_raw_quantile_crossing_rate"] = quantile_crossing_rate(
+        raw_weekly_quantiles
+    )
+    weekly_metrics["weekly_ordered_quantile_crossing_rate"] = quantile_crossing_rate(
+        weekly_quantiles
+    )
+    weekly_metrics["weekly_public_quantile_crossing_rate"] = weekly_metrics[
+        "weekly_ordered_quantile_crossing_rate"
+    ]
     weekly_metrics["weekly_magnitude_ratio"] = magnitude_ratio(weekly_actual, weekly_pred)
     weekly_metrics["weekly_mean_actual_abs"] = float(np.mean(np.abs(weekly_actual)))
     weekly_metrics["weekly_mean_pred_abs"] = float(np.mean(np.abs(weekly_pred)))

deep_learning/training/trainer.py

@@ -47,7 +47,7 @@ warnings.filterwarnings(
 logger = logging.getLogger(__name__)
 
 KNOWN_GOOD_CONFIG = {
-    "max_encoder_length": 60,
+    "max_encoder_length": 50,
     "hidden_size": 48,
     "attention_head_size": 2,
     "dropout": 0.30,
@@ -57,18 +57,15 @@ KNOWN_GOOD_CONFIG = {
     "lambda_vol": 0.30,
     "lambda_quantile": 0.25,
     "lambda_madl": 0.40,
-    "lambda_weekly_quantile": 0.60,
-    "lambda_t1_quantile": 0.10,
+    "lambda_weekly_quantile": 0.55,
+    "lambda_t1_quantile": 0.15,
+    "lambda_dispersion": 0.20,
     "lambda_directional": 0.10,
-    "lambda_magnitude": 0.55,
-    "weekly_lambda_vol": 0.35,
-    "lambda_width": 0.50,
-    "lambda_tail_width": 0.30,
-    "lambda_sanity": 0.20,
-    "lambda_crossing": 7.0,
     "batch_size": 32,
 }
 
+DETERMINISTIC_WEEKLY_CONFIG = dict(KNOWN_GOOD_CONFIG)
+
 REQUIRED_PROMOTABLE_METRICS = (
     "weekly_directional_accuracy",
     "weekly_magnitude_ratio",
@@ -126,13 +123,22 @@ def _compute_test_metrics_from_quantiles(
     pred_np: np.ndarray,
     cfg: TFTASROConfig,
 ) -> dict[str, float]:
-    from deep_learning.training.metrics import compute_all_metrics, compute_weekly_metrics, select_prediction_horizon
+    from deep_learning.training.metrics import (
+        compute_all_metrics,
+        compute_weekly_metrics,
+        monotonic_quantiles_np,
+        quantile_crossing_rate,
+        quantile_median_sort_gap,
+        select_prediction_horizon,
+    )
 
     pred_np = np.asarray(pred_np)
     _validate_quantile_prediction_shape(pred_np, cfg)
 
     median_idx = len(cfg.model.quantiles) // 2
-    pred_t1 = pred_np[:, 0, :]
+    ordered_pred_np = monotonic_quantiles_np(pred_np, median_idx=median_idx)
+    raw_pred_t1 = pred_np[:, 0, :]
+    pred_t1 = ordered_pred_np[:, 0, :]
     y_pred_median = pred_t1[:, median_idx]
     y_pred_q10 = pred_t1[:, 1]
     y_pred_q90 = pred_t1[:, -2]
@@ -150,6 +156,10 @@ def _compute_test_metrics_from_quantiles(
         y_pred_q98=y_pred_q98[:n],
         y_pred_quantiles=pred_t1[:n],
     )
+    raw_gap_mean, raw_gap_max = quantile_median_sort_gap(raw_pred_t1[:n], median_idx)
+    test_metrics["raw_quantile_crossing_rate"] = quantile_crossing_rate(raw_pred_t1[:n])
+    test_metrics["raw_median_sort_gap_mean"] = raw_gap_mean
+    test_metrics["raw_median_sort_gap_max"] = raw_gap_max
 
     n_path = min(len(y_actual_path), len(pred_np))
     weekly_metrics = compute_weekly_metrics(
@@ -167,6 +177,7 @@ def train_tft_model(
     cfg: Optional[TFTASROConfig] = None,
     use_asro: bool = True,
     upload_to_hub: bool = False,
+    deterministic_weekly_validation: bool = False,
 ) -> dict:
     """
     End-to-end TFT-ASRO training.
@@ -189,16 +200,23 @@ def train_tft_model(
     from deep_learning.data.feature_store import build_tft_dataframe
     from deep_learning.data.dataset import build_datasets, create_dataloaders
     from deep_learning.models.tft_copper import create_tft_model, get_variable_importance, format_prediction
-    from deep_learning.training.callbacks import CurriculumLossScheduler, SWACallback
+    from deep_learning.training.callbacks import (
+        CurriculumLossScheduler,
+        SWACallback,
+        WeeklyLossComponentLogger,
+    )
 
     if cfg is None:
         cfg = get_tft_config()
 
-    # ---- 0a. Load Optuna best params if available ----
-    # When the hyperopt step ran before this trainer, it writes best params to
-    # optuna_results.json. We apply those params over the default config so that
-    # the final training run actually benefits from the search.
-    cfg = _apply_optuna_results(cfg)
+    # ---- 0a. Load training params ----
+    # Deterministic validation bypasses Optuna so structural changes can be
+    # measured before investing in search.
+    if deterministic_weekly_validation:
+        cfg = _overlay_training_config(cfg, DETERMINISTIC_WEEKLY_CONFIG)
+        logger.info("Using deterministic weekly validation config: %s", DETERMINISTIC_WEEKLY_CONFIG)
+    else:
+        cfg = _apply_optuna_results(cfg)
 
     # ---- 0b. ASRO loss sanity check (runs before any training) ----
     try:
@@ -260,19 +278,11 @@ def train_tft_model(
             cfg.training.early_stopping_patience,
         )
         logger.info(
-            "Weekly loss   | weekly_q=%.2f t1_q=%.2f directional=%.2f magnitude=%.2f vol=%.2f",
+            "Weekly loss   | weekly_q=%.2f t1_q=%.2f dispersion=%.2f directional=%.2f monotonic_transform=true",
             cfg.weekly_loss.lambda_weekly_quantile,
             cfg.weekly_loss.lambda_t1_quantile,
+            cfg.weekly_loss.lambda_dispersion,
             cfg.weekly_loss.lambda_directional,
-            cfg.weekly_loss.lambda_magnitude,
-            cfg.weekly_loss.lambda_vol,
-        )
-        logger.info(
-            "Weekly guards | width=%.2f tail_width=%.2f crossing=%.2f sanity=%.2f",
-            cfg.weekly_loss.lambda_width,
-            cfg.weekly_loss.lambda_tail_width,
-            cfg.weekly_loss.lambda_crossing,
-            cfg.weekly_loss.lambda_sanity,
         )
     else:
         logger.info(
@@ -308,6 +318,7 @@ def train_tft_model(
             save_top_k=3,
             save_last=True,
         ),
+        WeeklyLossComponentLogger(),
     ]
 
     if use_asro and cfg.forecast.primary_horizon_days != 5:
@@ -430,12 +441,8 @@ def train_tft_model(
             "lambda_weekly_quantile": cfg.weekly_loss.lambda_weekly_quantile,
             "lambda_t1_quantile": cfg.weekly_loss.lambda_t1_quantile,
             "lambda_directional": cfg.weekly_loss.lambda_directional,
-            "lambda_magnitude": cfg.weekly_loss.lambda_magnitude,
-            "weekly_lambda_vol": cfg.weekly_loss.lambda_vol,
-            "weekly_lambda_crossing": cfg.weekly_loss.lambda_crossing,
-            "lambda_sanity": cfg.weekly_loss.lambda_sanity,
-            "lambda_width": cfg.weekly_loss.lambda_width,
-            "lambda_tail_width": cfg.weekly_loss.lambda_tail_width,
+            "lambda_dispersion": cfg.weekly_loss.lambda_dispersion,
+            "monotonic_quantile_transform": True,
             "max_encoder_length": cfg.model.max_encoder_length,
             "max_prediction_length": cfg.model.max_prediction_length,
             "forecast_contract_version": FORECAST_CONTRACT_VERSION,
@@ -518,7 +525,11 @@ def _write_conformal_calibration_artifact(
         import torch
 
         from deep_learning.calibration.conformal import rolling_conformal_adjustment
-        from deep_learning.training.metrics import cumulative_horizon, cumulative_quantiles
+        from deep_learning.training.metrics import (
+            cumulative_horizon,
+            cumulative_quantiles,
+            monotonic_quantiles_np,
+        )
 
         y_parts = []
         for batch in val_dl:
@@ -534,9 +545,13 @@ def _write_conformal_calibration_artifact(
             return None
 
         weekly_actual = cumulative_horizon(y_actual_path[:n], horizon=cfg.forecast.primary_horizon_days)
-        weekly_quantiles = np.sort(
-            cumulative_quantiles(pred_np[:n], horizon=cfg.forecast.primary_horizon_days),
-            axis=-1,
+        ordered_pred_np = monotonic_quantiles_np(
+            pred_np[:n],
+            median_idx=len(cfg.model.quantiles) // 2,
+        )
+        weekly_quantiles = cumulative_quantiles(
+            ordered_pred_np,
+            horizon=cfg.forecast.primary_horizon_days,
         )
         q = tuple(cfg.model.quantiles)
         q10_idx = q.index(0.10)
@@ -638,18 +653,10 @@ def _apply_optuna_results(cfg: TFTASROConfig) -> TFTASROConfig:
             params["learning_rate"] = min(float(params["learning_rate"]), 6e-4)
         if "weight_decay" in params:
             params["weight_decay"] = min(float(params["weight_decay"]), 5e-4)
-        if "lambda_magnitude" in params:
-            params["lambda_magnitude"] = max(float(params["lambda_magnitude"]), 0.50)
         if "lambda_directional" in params:
             params["lambda_directional"] = min(float(params["lambda_directional"]), 0.12)
-        if "lambda_width" in params:
-            params["lambda_width"] = max(float(params["lambda_width"]), 0.40)
-        if "lambda_tail_width" in params:
-            params["lambda_tail_width"] = max(float(params["lambda_tail_width"]), 0.25)
-        if "lambda_sanity" in params:
-            params["lambda_sanity"] = max(float(params["lambda_sanity"]), 0.10)
-        if "lambda_crossing" in params:
-            params["lambda_crossing"] = max(float(params["lambda_crossing"]), 5.0)
+        if "lambda_dispersion" in params:
+            params["lambda_dispersion"] = max(float(params["lambda_dispersion"]), 0.20)
 
         logger.info(
             "Loaded Optuna best params (trial #%d, weekly_objective=%.4f): %s",
@@ -685,12 +692,9 @@ def _overlay_training_config(cfg: TFTASROConfig, params: dict) -> TFTASROConfig:
     weekly_loss_overrides = {
         k: params[k] for k in (
             "lambda_weekly_quantile", "lambda_t1_quantile", "lambda_directional",
-            "lambda_magnitude", "lambda_crossing", "lambda_sanity",
-            "lambda_width", "lambda_tail_width",
+            "lambda_dispersion",
         ) if k in params
     }
-    if "weekly_lambda_vol" in params:
-        weekly_loss_overrides["lambda_vol"] = params["weekly_lambda_vol"]
 
     new_model = replace(cfg.model, **model_overrides) if model_overrides else cfg.model
     new_asro = replace(cfg.asro, **asro_overrides) if asro_overrides else cfg.asro
@@ -744,10 +748,20 @@ if __name__ == "__main__":
     parser.add_argument("--symbol", default="HG=F")
     parser.add_argument("--no-asro", action="store_true", help="Use standard QuantileLoss instead of ASRO")
     parser.add_argument("--upload-hub", action="store_true", help="Upload artifacts to HF Hub after training")
+    parser.add_argument(
+        "--deterministic-weekly-validation",
+        action="store_true",
+        help="Bypass Optuna overlays and run the fixed monotonic weekly validation config",
+    )
     args = parser.parse_args()
 
     cfg = get_tft_config()
-    result = train_tft_model(cfg, use_asro=not args.no_asro, upload_to_hub=args.upload_hub)
+    result = train_tft_model(
+        cfg,
+        use_asro=not args.no_asro,
+        upload_to_hub=args.upload_hub,
+        deterministic_weekly_validation=args.deterministic_weekly_validation,
+    )
 
     print("\n" + "=" * 60)
     print("TFT-ASRO TRAINING COMPLETE")

scripts/tft_quality_gate.py

@@ -19,7 +19,7 @@ BACKEND_ROOT = pathlib.Path(__file__).resolve().parents[1]
 if str(BACKEND_ROOT) not in sys.path:
     sys.path.insert(0, str(BACKEND_ROOT))
 
-from app.quality_gate import evaluate_quality_gate
+from app.quality_gate import evaluate_quality_gate, evaluate_quality_gate_warnings
 
 META_PATH = pathlib.Path(os.environ.get("TFT_METADATA_PATH", "/tmp/models/tft/tft_metadata.json"))
 
@@ -37,17 +37,23 @@ def main() -> int:
     tail_capture = metrics.get("tail_capture_rate")
     quantile_crossing = metrics.get("quantile_crossing_rate")
     median_gap_max = metrics.get("median_sort_gap_max")
+    pi80_width = metrics.get("pi80_width")
+    pi96_width = metrics.get("pi96_width")
+    mae_vs_naive_zero = metrics.get("mae_vs_naive_zero")
     weekly_da = metrics.get("weekly_directional_accuracy")
     weekly_mr = metrics.get("weekly_magnitude_ratio")
     weekly_tail = metrics.get("weekly_tail_capture_rate")
     weekly_pi80 = metrics.get("weekly_pi80_coverage")
+    weekly_pi80_width = metrics.get("weekly_pi80_width")
     weekly_pi80_width_ratio = metrics.get("weekly_pi80_width_ratio")
     weekly_pi96 = metrics.get("weekly_pi96_coverage")
+    weekly_pi96_width = metrics.get("weekly_pi96_width")
     weekly_pi96_width_ratio = metrics.get("weekly_pi96_width_ratio")
     weekly_qcross = metrics.get("weekly_quantile_crossing_rate")
     weekly_sorted_qcross = metrics.get("weekly_sorted_quantile_crossing_rate")
     weekly_gap = metrics.get("weekly_median_sort_gap_max")
     weekly_samples = metrics.get("weekly_sample_count")
+    weekly_mae_vs_naive_zero = metrics.get("weekly_mae_vs_naive_zero")
 
     print(
         "Quality gate metrics: "
@@ -71,18 +77,29 @@ def main() -> int:
         tail_capture=tail_capture,
         quantile_crossing_rate=quantile_crossing,
         median_sort_gap_max=median_gap_max,
+        pi80_width=pi80_width,
+        pi96_width=pi96_width,
         weekly_directional_accuracy=weekly_da,
         weekly_magnitude_ratio=weekly_mr,
         weekly_tail_capture_rate=weekly_tail,
         weekly_pi80_coverage=weekly_pi80,
+        weekly_pi80_width=weekly_pi80_width,
         weekly_pi80_width_ratio=weekly_pi80_width_ratio,
         weekly_pi96_coverage=weekly_pi96,
+        weekly_pi96_width=weekly_pi96_width,
         weekly_pi96_width_ratio=weekly_pi96_width_ratio,
         weekly_quantile_crossing_rate=weekly_qcross,
         weekly_sorted_quantile_crossing_rate=weekly_sorted_qcross,
         weekly_median_sort_gap_max=weekly_gap,
         weekly_sample_count=weekly_samples,
     )
+    warnings = evaluate_quality_gate_warnings(
+        vr=vr,
+        mae_vs_naive_zero=mae_vs_naive_zero,
+        weekly_mae_vs_naive_zero=weekly_mae_vs_naive_zero,
+    )
+    for warning in warnings:
+        print(f"QUALITY GATE WARNING: {warning}")
 
     if passed:
         print("QUALITY GATE: PASSED")