
# -*- coding: utf-8 -*-
"""Suite18 FMM representation layer.

The module is deliberately independent from Suite17.  It transforms an existing
Suite17 view into chronology-safe fuzzy-min-max descriptors and never changes the
Committee or the downstream Newton-HGB learner.

Chronology contract
-------------------
For historical block b, descriptors are computed BEFORE labels from b update the
hyperboxes.  Feature selection and min/max normalization are fitted once on the
first sufficiently-supported strict historical prefix and then frozen.  This
keeps all historical and target descriptors in one coordinate system while
ensuring that no future/current-block label can influence a historical row.

The target descriptor is generated by the final state after every available
historical block has been absorbed.  Target labels are never consumed.
"""
from __future__ import annotations

from dataclasses import dataclass, field
from typing import Sequence
import math
import warnings

import numpy as np
import pandas as pd
from sklearn.feature_selection import f_classif
from sklearn.tree import DecisionTreeClassifier
from sklearn.ensemble import RandomForestClassifier
from scipy.spatial import cKDTree


EPS = 1e-9


@dataclass(frozen=True)
class FMMConfig:
    top_k: int = 32
    thetas: tuple[float, ...] = (0.15, 0.30, 0.50)
    gamma: float = 1.0
    confidence_k: float = 0.50
    min_history_rows: int = 5000
    min_history_failures: int = 50
    chunk_size: int = 1024
    random_state: int = 20260901

    def validate(self) -> "FMMConfig":
        if self.top_k < 1:
            raise ValueError("top_k must be >=1")
        if not self.thetas or any(t <= 0 or t > 1 for t in self.thetas):
            raise ValueError("all theta values must lie in (0,1]")
        if self.gamma <= 0:
            raise ValueError("gamma must be >0")
        if not 0 <= self.confidence_k <= 1:
            raise ValueError("confidence_k must lie in [0,1]")
        if self.min_history_rows < 2 or self.min_history_failures < 1:
            raise ValueError("invalid minimum FMM history support")
        if self.chunk_size < 1:
            raise ValueError("chunk_size must be >=1")
        return self


class FrozenTopKMinMax:
    """Training-prefix-only ANOVA selector + median imputer + [0,1] scaler."""

    def __init__(self, top_k: int = 32):
        self.top_k = int(top_k)
        self.feature_names_: list[str] = []
        self.selected_indices_: np.ndarray | None = None
        self.selected_feature_names_: list[str] = []
        self.scores_: np.ndarray | None = None
        self.median_: np.ndarray | None = None
        self.min_: np.ndarray | None = None
        self.max_: np.ndarray | None = None
        self.scale_: np.ndarray | None = None
        self.report_: list[dict] = []

    @staticmethod
    def _as_2d(X):
        a = np.asarray(X, dtype=np.float64)
        if a.ndim != 2:
            raise ValueError(f"X must be 2-D, got {a.shape}")
        return a

    def fit(self, X, y, feature_names: Sequence[str]):
        X = self._as_2d(X)
        y = np.asarray(y, int).reshape(-1)
        names = list(feature_names)
        if X.shape[1] != len(names):
            raise ValueError("feature_names length does not match X")
        if len(X) != len(y) or len(X) < 2 or np.unique(y).size < 2:
            raise ValueError("FMM preprocessing requires >=2 rows and both classes")

        # Prefix-only median imputation.  Non-finite values never leak extrema.
        finite = np.where(np.isfinite(X), X, np.nan)
        med = np.nanmedian(finite, axis=0)
        med = np.where(np.isfinite(med), med, 0.0)
        Xi = np.where(np.isfinite(X), X, med)

        with warnings.catch_warnings():
            warnings.simplefilter("ignore")
            scores, _ = f_classif(Xi, y)
        scores = np.asarray(scores, float)
        rank_score = np.nan_to_num(scores, nan=-np.inf, posinf=np.finfo(float).max, neginf=-np.inf)
        order = np.lexsort((np.arange(X.shape[1]), -rank_score))
        k = min(max(1, self.top_k), X.shape[1])
        selected = np.sort(order[:k])

        Z = Xi[:, selected]
        lo = np.min(Z, axis=0)
        hi = np.max(Z, axis=0)
        scale = np.where((hi - lo) > 1e-12, hi - lo, 1.0)

        self.feature_names_ = names
        self.selected_indices_ = selected.astype(np.int64)
        self.selected_feature_names_ = [names[i] for i in selected]
        self.scores_ = scores
        self.median_ = med
        self.min_ = lo.astype(np.float64)
        self.max_ = hi.astype(np.float64)
        self.scale_ = scale.astype(np.float64)

        rank = {int(i): r + 1 for r, i in enumerate(order)}
        chosen = set(selected.tolist())
        self.report_ = [
            {
                "raw_feature_index": int(i),
                "feature": names[i],
                "f_score": float(scores[i]) if np.isfinite(scores[i]) else np.nan,
                "rank": int(rank[i]),
                "selected": bool(i in chosen),
            }
            for i in range(X.shape[1])
        ]
        return self

    def transform(self, X):
        if self.selected_indices_ is None:
            raise RuntimeError("FrozenTopKMinMax is not fitted")
        X = self._as_2d(X)
        if X.shape[1] != len(self.feature_names_):
            raise ValueError("query feature dimension differs from fitted view")
        Xi = np.where(np.isfinite(X), X, self.median_)
        Z = Xi[:, self.selected_indices_]
        Z = (Z - self.min_) / self.scale_
        return np.clip(np.nan_to_num(Z, nan=0.0, posinf=1.0, neginf=0.0), 0.0, 1.0).astype(np.float32)



class IncrementalFMM:
    """Binary labelled fuzzy min-max learner with exact spatial acceleration.

    Expansion candidates are queried by centroid in L-infinity radius theta.
    This is exact (not approximate): if adding x keeps every hyperbox dimension
    <= theta, the current centroid must be within L-infinity distance theta of x.

    Prediction is an exact nearest-axis-aligned-hyperbox query.  A cKDTree over
    hyperbox centroids supplies a provable candidate radius:
        rect_distance(x, B) >= center_distance_inf(x, c_B) - max_half_width.
    Therefore no box outside best_rect_distance + max_half_width can improve the
    current best membership.
    """

    def __init__(self, theta=.30, gamma=1.0, confidence_k=.50, chunk_size=1024):
        self.theta = float(theta)
        self.gamma = float(gamma)
        self.confidence_k = float(confidence_k)
        self.chunk_size = int(chunk_size)

        self.v_: np.ndarray | None = None
        self.w_: np.ndarray | None = None
        self.centroid_: np.ndarray | None = None
        self.support_: np.ndarray = np.zeros(0, np.int64)
        self.label_: np.ndarray = np.zeros(0, np.int8)
        self.usage_: np.ndarray = np.zeros(0, np.int64)
        self.correct_: np.ndarray = np.zeros(0, np.int64)
        self.contraction_events_: int = 0

        # Training-time dynamic spatial index.  Trees contain only boxes that
        # have not moved since the last rebuild; moved/new boxes are held in the
        # exact brute-force dirty set until the next rebuild.
        self._train_trees: dict[int, tuple[cKDTree, np.ndarray] | None] = {0: None, 1: None}
        self._dirty_boxes: set[int] = set()
        self._tree_rebuild_min = 64

    @property
    def n_boxes(self):
        return int(len(self.label_))

    @property
    def dim(self):
        return 0 if self.v_ is None else int(self.v_.shape[1])

    def _mark_dirty(self, *indices):
        for i in indices:
            if i is not None and int(i) >= 0:
                self._dirty_boxes.add(int(i))

    def _append_box(self, x, label):
        x = np.asarray(x, np.float32).reshape(1, -1)
        if self.v_ is None:
            self.v_ = x.copy()
            self.w_ = x.copy()
            self.centroid_ = x.copy()
        else:
            self.v_ = np.vstack([self.v_, x])
            self.w_ = np.vstack([self.w_, x])
            self.centroid_ = np.vstack([self.centroid_, x])
        self.support_ = np.append(self.support_, 1)
        self.label_ = np.append(self.label_, np.int8(label))
        self.usage_ = np.append(self.usage_, 0)
        self.correct_ = np.append(self.correct_, 0)
        idx = self.n_boxes - 1
        self._mark_dirty(idx)
        return idx

    def _rebuild_training_trees(self):
        for cls in (0, 1):
            idx = np.where(self.label_ == cls)[0].astype(np.int64)
            self._train_trees[cls] = (
                None if len(idx) == 0 else (cKDTree(self.centroid_[idx]), idx)
            )
        self._dirty_boxes.clear()

    def _maybe_rebuild_training_trees(self):
        if self.n_boxes < self._tree_rebuild_min:
            return
        no_tree = all(v is None for v in self._train_trees.values())
        dirty_limit = max(self._tree_rebuild_min, int(math.ceil(.05 * self.n_boxes)))
        if no_tree or len(self._dirty_boxes) >= dirty_limit:
            self._rebuild_training_trees()

    def _candidate_indices(self, x, label):
        """Exact superset of all same-class theta-expandable boxes."""
        same = np.where(self.label_ == int(label))[0].astype(np.int64)
        if len(same) == 0:
            return same
        if self.n_boxes < self._tree_rebuild_min:
            return same

        self._maybe_rebuild_training_trees()
        stable = []
        tree_item = self._train_trees.get(int(label))
        if tree_item is not None:
            tree, global_idx = tree_item
            local = tree.query_ball_point(np.asarray(x, float), r=self.theta + 1e-12, p=np.inf)
            if len(local):
                stable = [
                    int(global_idx[j]) for j in local
                    if int(global_idx[j]) not in self._dirty_boxes
                ]

        dirty = [
            i for i in self._dirty_boxes
            if i < self.n_boxes and int(self.label_[i]) == int(label)
        ]
        if not stable:
            return np.asarray(sorted(set(dirty)), np.int64)
        if not dirty:
            return np.asarray(sorted(set(stable)), np.int64)
        return np.asarray(sorted(set(stable).union(dirty)), np.int64)

    def _membership_single_to_indices(self, x, idx):
        if len(idx) == 0:
            return np.zeros(0, float)
        V = self.v_[idx]
        W = self.w_[idx]
        outside = np.maximum(np.maximum(V - x, x - W), 0.0)
        d = np.max(outside, axis=1)
        return np.clip(1.0 - self.gamma * d, 0.0, 1.0)

    def _best_expandable(self, x, label):
        idx = self._candidate_indices(x, label)
        if len(idx) == 0:
            return None
        nv = np.minimum(self.v_[idx], x)
        nw = np.maximum(self.w_[idx], x)
        widths = nw - nv
        ok = np.all(widths <= self.theta + 1e-12, axis=1)
        if not np.any(ok):
            return None
        cand = idx[ok]
        old_width = self.w_[cand] - self.v_[cand]
        new_width = np.maximum(self.w_[cand], x) - np.minimum(self.v_[cand], x)
        expansion = np.sum(new_width - old_width, axis=1)
        membership = self._membership_single_to_indices(x, cand)
        order = np.lexsort((cand, -membership, expansion))
        return int(cand[int(order[0])])

    def _contract_pair(self, i, j):
        lo = np.maximum(self.v_[i], self.v_[j])
        hi = np.minimum(self.w_[i], self.w_[j])
        overlap = hi - lo
        if not np.all(overlap > 1e-12):
            return False
        d = int(np.argmin(overlap))
        ci = float(self.centroid_[i, d])
        cj = float(self.centroid_[j, d])
        boundary = 0.5 * (ci + cj)
        if ci <= cj:
            self.w_[i, d] = min(float(self.w_[i, d]), boundary)
            self.v_[j, d] = max(float(self.v_[j, d]), boundary)
        else:
            self.w_[j, d] = min(float(self.w_[j, d]), boundary)
            self.v_[i, d] = max(float(self.v_[i, d]), boundary)

        # Keep each centroid inside its contracted box.
        self.v_[i, d] = min(self.v_[i, d], self.centroid_[i, d])
        self.w_[i, d] = max(self.w_[i, d], self.centroid_[i, d])
        self.v_[j, d] = min(self.v_[j, d], self.centroid_[j, d])
        self.w_[j, d] = max(self.w_[j, d], self.centroid_[j, d])
        self.contraction_events_ += 1
        self._mark_dirty(i, j)
        return True

    def partial_fit(self, X, y):
        X = np.asarray(X, np.float32)
        y = np.asarray(y, int).reshape(-1)
        if X.ndim != 2 or len(X) != len(y):
            raise ValueError("X/y shape mismatch")
        if len(X) == 0:
            return self
        if self.v_ is not None and X.shape[1] != self.dim:
            raise ValueError("FMM input dimension changed")

        for x, cls in zip(X, y):
            cls = int(cls)
            if cls not in (0, 1):
                raise ValueError("IncrementalFMM supports binary labels 0/1")
            chosen = self._best_expandable(x, cls)
            if chosen is None:
                chosen = self._append_box(x, cls)
            else:
                old_n = int(self.support_[chosen])
                self.v_[chosen] = np.minimum(self.v_[chosen], x)
                self.w_[chosen] = np.maximum(self.w_[chosen], x)
                self.centroid_[chosen] = (
                    self.centroid_[chosen] + (x - self.centroid_[chosen]) / float(old_n + 1)
                )
                self.support_[chosen] = old_n + 1
                self._mark_dirty(chosen)

            # Vectorized overlap prefilter; contract only true opposing overlaps.
            opp = np.where(self.label_ != cls)[0]
            if len(opp):
                lo = np.maximum(self.v_[chosen][None, :], self.v_[opp])
                hi = np.minimum(self.w_[chosen][None, :], self.w_[opp])
                hit = opp[np.all((hi - lo) > 1e-12, axis=1)]
                for j in hit:
                    self._contract_pair(chosen, int(j))
        return self

    def confidence_components(self):
        n = self.n_boxes
        usage_norm = np.zeros(n, float)
        acc_norm = np.zeros(n, float)
        for cls in (0, 1):
            idx = np.where(self.label_ == cls)[0]
            if len(idx) == 0:
                continue
            mu = int(np.max(self.usage_[idx])) if len(idx) else 0
            mc = int(np.max(self.correct_[idx])) if len(idx) else 0
            if mu > 0:
                usage_norm[idx] = self.usage_[idx] / float(mu)
            if mc > 0:
                acc_norm[idx] = self.correct_[idx] / float(mc)
        cf = (1.0 - self.confidence_k) * usage_norm + self.confidence_k * acc_norm
        return usage_norm, acc_norm, np.clip(cf, 0.0, 1.0)

    @staticmethod
    def _rectangle_distance_one(x, V, W):
        outside = np.maximum(np.maximum(V - x, x - W), 0.0)
        return np.max(outside, axis=1)

    def _class_best_boxes(self, Q, cls, cf):
        """Exact nearest-rectangle box, distance and membership for one class."""
        idx = np.where(self.label_ == int(cls))[0].astype(np.int64)
        n = len(Q)
        if len(idx) == 0:
            return (
                np.full(n, np.inf, float),
                np.zeros(n, np.float32),
                np.full(n, -1, np.int64),
            )

        centers = self.centroid_[idx]
        tree = cKDTree(centers)
        _, nearest_local = tree.query(Q, k=1, p=np.inf)
        nearest_local = np.asarray(nearest_local, int).reshape(-1)
        nearest_global = idx[nearest_local]

        best_d = np.empty(n, float)
        for i in range(n):
            g = int(nearest_global[i])
            best_d[i] = float(self._rectangle_distance_one(
                Q[i], self.v_[g:g+1], self.w_[g:g+1]
            )[0])

        half = .5 * np.maximum(self.w_[idx] - self.v_[idx], 0.0)
        max_half = float(np.max(half)) if half.size else 0.0
        radius = best_d + max_half + 1e-12
        candidate_lists = tree.query_ball_point(Q, r=radius, p=np.inf)

        winner = nearest_global.copy()
        for i, local in enumerate(candidate_lists):
            if not len(local):
                continue
            cand = idx[np.asarray(local, int)]
            d = self._rectangle_distance_one(Q[i], self.v_[cand], self.w_[cand])
            dmin = float(np.min(d))
            tie = cand[np.isclose(d, dmin, rtol=0.0, atol=1e-12)]
            if len(tie) > 1:
                # Centroid distance is the first tie-break (paper-compatible
                # centroid information); CF then support; box id is deterministic.
                cdist = np.max(np.abs(self.centroid_[tie] - Q[i]), axis=1)
                minc = np.min(cdist)
                tie2 = tie[np.isclose(cdist, minc, rtol=0.0, atol=1e-12)]
                if len(tie2) > 1:
                    cfs = cf[tie2]
                    maxcf = np.max(cfs)
                    tie3 = tie2[np.isclose(cfs, maxcf, rtol=0.0, atol=1e-12)]
                    if len(tie3) > 1:
                        sup = self.support_[tie3]
                        tie3 = tie3[sup == np.max(sup)]
                    winner[i] = int(np.min(tie3))
                else:
                    winner[i] = int(tie2[0])
            else:
                winner[i] = int(tie[0])
            best_d[i] = dmin

        membership = np.clip(1.0 - self.gamma * best_d, 0.0, 1.0).astype(np.float32)
        return best_d, membership, winner

    def describe(self, X):
        """Return 14 exact FMM descriptors and winning hyperbox ids."""
        X = np.asarray(X, np.float32)
        if X.ndim != 2:
            raise ValueError("X must be 2-D")
        out = np.zeros((len(X), 14), np.float32)
        winners = np.full(len(X), -1, np.int64)
        if self.n_boxes == 0:
            return out, winners

        _, _, cf = self.confidence_components()
        for start in range(0, len(X), self.chunk_size):
            stop = min(start + self.chunk_size, len(X))
            Q = X[start:stop]
            d0, m0, w0 = self._class_best_boxes(Q, 0, cf)
            d1, m1, w1 = self._class_best_boxes(Q, 1, cf)

            choose1 = d1 < d0
            tie = np.isclose(d1, d0, rtol=0.0, atol=1e-12)
            if np.any(tie):
                c0 = np.where(w0 >= 0, cf[np.maximum(w0, 0)], -1.0)
                c1 = np.where(w1 >= 0, cf[np.maximum(w1, 0)], -1.0)
                choose1[tie] = c1[tie] > c0[tie]
            win = np.where(choose1, w1, w0).astype(np.int64)
            # Both classes exist after initialization; this is defensive only.
            missing = win < 0
            if np.any(missing):
                win[missing] = np.where(w1[missing] >= 0, w1[missing], w0[missing])

            winners[start:stop] = win
            denom = m0 + m1
            f_norm = np.divide(m1, denom, out=np.zeros_like(m1), where=denom > EPS)
            gap = np.abs(m1 - m0)
            maxm = np.maximum(m0, m1)
            winner_failure = self.label_[win].astype(float)
            supp = self.support_[win].astype(float)
            C = self.centroid_[win]
            width = np.maximum(self.w_[win] - self.v_[win], 0.0)
            l1 = np.mean(np.abs(Q - C), axis=1)
            l2 = np.sqrt(np.mean((Q - C) ** 2, axis=1))
            mean_width = np.mean(width, axis=1)
            log_volume = np.mean(np.log(np.clip(width, 1e-6, 1.0)), axis=1)
            chosen_d = np.where(choose1, d1, d0)
            inside = (chosen_d <= 1e-12).astype(float)

            out[start:stop] = np.column_stack([
                m0, m1, f_norm, m1 - m0, maxm, gap, winner_failure,
                cf[win], np.log1p(supp), l1, l2, mean_width, log_volume, inside,
            ]).astype(np.float32)
        return out, winners

    def update_confidence(self, winners, y_true):
        winners = np.asarray(winners, int).reshape(-1)
        y_true = np.asarray(y_true, int).reshape(-1)
        if len(winners) != len(y_true):
            raise ValueError("winner/y length mismatch")
        valid = winners >= 0
        if not np.any(valid):
            return self
        for box in np.unique(winners[valid]):
            m = winners == box
            self.usage_[box] += int(np.sum(m))
            self.correct_[box] += int(np.sum(y_true[m] == int(self.label_[box])))
        return self

    def hyperbox_rows(self, view_name="", theta=None):
        u, a, cf = self.confidence_components()
        rows = []
        for i in range(self.n_boxes):
            width = np.maximum(self.w_[i] - self.v_[i], 0.0)
            rows.append({
                "view": view_name,
                "theta": self.theta if theta is None else float(theta),
                "box_id": int(i),
                "class": int(self.label_[i]),
                "support": int(self.support_[i]),
                "usage_count": int(self.usage_[i]),
                "correct_count": int(self.correct_[i]),
                "normalized_usage": float(u[i]),
                "normalized_accuracy": float(a[i]),
                "confidence_factor": float(cf[i]),
                "mean_width": float(np.mean(width)),
                "max_width": float(np.max(width)),
                "log_volume_mean": float(np.mean(np.log(np.clip(width, 1e-6, 1.0)))),
            })
        return rows

    def centroid_training_set(self):
        if self.n_boxes == 0:
            return np.zeros((0, 0), np.float32), np.zeros(0, int), np.zeros(0, float)
        _, _, cf = self.confidence_components()
        return self.centroid_.copy(), self.label_.astype(int).copy(), cf.astype(float).copy()

_BASE_DESCRIPTOR_NAMES = [
    "membership_normal",
    "membership_failure",
    "normalized_failure_membership",
    "failure_minus_normal_membership",
    "maximum_membership",
    "top1_top2_membership_gap",
    "winner_is_failure",
    "winner_confidence_factor",
    "log1p_winner_support",
    "winner_centroid_l1_distance",
    "winner_centroid_l2_distance",
    "winner_mean_width",
    "winner_log_volume",
    "inside_winner_hyperbox",
]


def _theta_tag(theta):
    return f"{float(theta):.2f}".replace(".", "p")


def descriptor_feature_names(thetas=(.15, .30, .50)):
    names = []
    for t in thetas:
        names += [f"fmm_t{_theta_tag(t)}_{n}" for n in _BASE_DESCRIPTOR_NAMES]
    names += [
        "fmm_failure_mean",
        "fmm_failure_std",
        "fmm_failure_max",
        "fmm_scale_agreement",
    ]
    return names


def combine_multiscale(per_scale, thetas):
    if len(per_scale) != len(thetas):
        raise ValueError("per_scale/thetas mismatch")
    if not per_scale:
        return np.zeros((0, 0), np.float32)
    blocks = [np.asarray(z, np.float32) for z in per_scale]
    n = len(blocks[0])
    if any(len(z) != n or z.shape[1] != 14 for z in blocks):
        raise ValueError("invalid scale descriptor shape")
    failure = np.column_stack([z[:, 2] for z in blocks])
    winners = np.column_stack([z[:, 6] for z in blocks])
    ones = np.sum(winners >= .5, axis=1)
    zeros = len(blocks) - ones
    agreement = np.maximum(ones, zeros) / float(len(blocks))
    cross = np.column_stack([
        np.mean(failure, axis=1),
        np.std(failure, axis=1),
        np.max(failure, axis=1),
        agreement,
    ]).astype(np.float32)
    return np.column_stack(blocks + [cross]).astype(np.float32)


@dataclass
class FMMRepresentationResult:
    view_name: str
    hist_descriptor: np.ndarray
    target_descriptor: np.ndarray
    feature_names: list[str]
    preprocessor: FrozenTopKMinMax | None
    models: dict[float, IncrementalFMM]
    block_audit: list[dict] = field(default_factory=list)
    feature_selection_rows: list[dict] = field(default_factory=list)
    hyperbox_rows: list[dict] = field(default_factory=list)
    target_selected_scaled: np.ndarray | None = None
    initialization_block: float | None = None

    @property
    def available(self):
        return self.preprocessor is not None and bool(self.models)


def _supported_prefix(y, idx, cfg):
    if len(idx) < cfg.min_history_rows:
        return False
    yy = np.asarray(y, int)[idx]
    if np.unique(yy).size < 2:
        return False
    counts = np.bincount(yy, minlength=2)
    return int(np.min(counts)) >= int(cfg.min_history_failures)


def build_prequential_fmm_representation(
    X_hist, y_hist, blocks, X_target, feature_names, config: FMMConfig, view_name="VIEW"
):
    """Build a strict query-before-update multiscale FMM representation."""
    cfg = config.validate()
    Xh = np.asarray(X_hist, np.float32)
    Xt = np.asarray(X_target, np.float32)
    y = np.asarray(y_hist, int).reshape(-1)
    b = np.asarray(blocks, float).reshape(-1)
    if Xh.ndim != 2 or Xt.ndim != 2 or Xh.shape[1] != Xt.shape[1]:
        raise ValueError("historical/target view dimensions do not match")
    if len(Xh) != len(y) or len(y) != len(b):
        raise ValueError("historical row alignment mismatch")
    if Xh.shape[1] != len(feature_names):
        raise ValueError("feature names do not match view dimension")

    names = descriptor_feature_names(cfg.thetas)
    Dh = np.zeros((len(Xh), len(names)), np.float32)
    Dt = np.zeros((len(Xt), len(names)), np.float32)
    prep = None
    models: dict[float, IncrementalFMM] = {}
    audits = []
    init_block = None

    uniq = np.array(sorted(x for x in pd.unique(b[np.isfinite(b)])), dtype=float)
    for block in uniq:
        query = np.where(b == block)[0]
        prior = np.where(np.isfinite(b) & (b < block))[0]

        if prep is None and _supported_prefix(y, prior, cfg):
            prep = FrozenTopKMinMax(cfg.top_k).fit(Xh[prior], y[prior], feature_names)
            Zp = prep.transform(Xh[prior])
            models = {
                float(t): IncrementalFMM(t, cfg.gamma, cfg.confidence_k, cfg.chunk_size)
                for t in cfg.thetas
            }
            for model in models.values():
                model.partial_fit(Zp, y[prior])
            init_block = float(block)

        if prep is None:
            audits.append({
                "view": view_name,
                "query_block": float(block),
                "query_rows": int(len(query)),
                "train_rows": int(len(prior)),
                "train_failures": int(np.sum(y[prior])),
                "max_train_block": float(np.max(b[prior])) if len(prior) else np.nan,
                "available": False,
                "reason": "insufficient_strict_prior_history",
            })
            continue

        Zq = prep.transform(Xh[query])
        scale_desc = []
        winners = {}
        for t in cfg.thetas:
            d, w = models[float(t)].describe(Zq)
            scale_desc.append(d)
            winners[float(t)] = w
        Dh[query] = combine_multiscale(scale_desc, cfg.thetas)

        # Only after descriptors are frozen for block b may labels from b be used.
        for t in cfg.thetas:
            model = models[float(t)]
            model.update_confidence(winners[float(t)], y[query])
            model.partial_fit(Zq, y[query])

        audits.append({
            "view": view_name,
            "query_block": float(block),
            "query_rows": int(len(query)),
            "train_rows": int(len(prior)),
            "train_failures": int(np.sum(y[prior])),
            "max_train_block": float(np.max(b[prior])) if len(prior) else np.nan,
            "available": True,
            "reason": "strict_prior_only",
            "initialization_block": init_block,
            **{
                f"boxes_theta_{_theta_tag(t)}": int(models[float(t)].n_boxes)
                for t in cfg.thetas
            },
        })

    if prep is not None:
        Zt = prep.transform(Xt)
        target_scale = [models[float(t)].describe(Zt)[0] for t in cfg.thetas]
        Dt = combine_multiscale(target_scale, cfg.thetas)
    else:
        Zt = None

    fs = []
    if prep is not None:
        fs = [dict(view=view_name, initialization_block=init_block, **r) for r in prep.report_]

    hb = []
    for t in cfg.thetas:
        if float(t) in models:
            hb.extend(models[float(t)].hyperbox_rows(view_name, t))

    return FMMRepresentationResult(
        view_name=view_name,
        hist_descriptor=Dh,
        target_descriptor=Dt,
        feature_names=names,
        preprocessor=prep,
        models=models,
        block_audit=audits,
        feature_selection_rows=fs,
        hyperbox_rows=hb,
        target_selected_scaled=Zt,
        initialization_block=init_block,
    )


def paper_hybrid_predictions(
    result: FMMRepresentationResult,
    theta=.30,
    cart_max_depth=None,
    rf_trees=200,
    seed=20260901,
):
    """Paper-inspired hyperbox-centroid -> CART/RF diagnostic.

    Hyperbox centroids are tree training samples; the paper confidence factor is
    passed as sample_weight, which makes sklearn's class counts/Gini weighted by
    FMM confidence.  This branch never consumes target labels.
    """
    n = len(result.target_descriptor)
    empty = {
        "fmm_standalone": np.zeros(n, np.float32),
        "fmm_cart": np.zeros(n, np.float32),
        "fmm_rf": np.zeros(n, np.float32),
        "available": False,
        "hyperbox_training_rows": 0,
    }
    if not result.available or result.target_selected_scaled is None:
        return empty

    thetas = list(result.models)
    if not thetas:
        return empty
    chosen = min(thetas, key=lambda t: abs(float(t) - float(theta)))
    model = result.models[chosen]
    centroids, labels, cf = model.centroid_training_set()
    if len(centroids) < 2 or np.unique(labels).size < 2:
        return empty

    # The standalone score is the normalized failure membership for chosen scale.
    cfg_thetas = tuple(result.models.keys())
    pos = cfg_thetas.index(chosen)
    fmm_score = result.target_descriptor[:, pos * 14 + 2].astype(np.float32)

    # Zero-CF boxes are retained with a negligible weight so that newly-created,
    # as-yet-unused boxes are represented without dominating the tree.
    sw = np.maximum(np.asarray(cf, float), 1e-6)
    cart = DecisionTreeClassifier(max_depth=cart_max_depth, random_state=int(seed))
    cart.fit(centroids, labels, sample_weight=sw)
    rf = RandomForestClassifier(
        n_estimators=int(rf_trees),
        max_features="sqrt",
        class_weight=None,
        n_jobs=-1,
        random_state=int(seed) + 1,
    )
    rf.fit(centroids, labels, sample_weight=sw)

    def pos_proba(est):
        p = np.asarray(est.predict_proba(result.target_selected_scaled), float)
        cls = np.asarray(est.classes_)
        j = np.where(cls == 1)[0]
        return np.zeros(n, np.float32) if len(j) != 1 else p[:, int(j[0])].astype(np.float32)

    return {
        "fmm_standalone": fmm_score,
        "fmm_cart": pos_proba(cart),
        "fmm_rf": pos_proba(rf),
        "available": True,
        "theta": float(chosen),
        "hyperbox_training_rows": int(len(labels)),
        "hyperbox_failures": int(np.sum(labels == 1)),
        "mean_confidence_factor": float(np.mean(cf)),
    }


def hyperbox_scale_summary(result: FMMRepresentationResult):
    rows = []
    for theta, model in result.models.items():
        _, _, cf = model.confidence_components()
        for cls in (0, 1):
            idx = np.where(model.label_ == cls)[0]
            if len(idx) == 0:
                rows.append({
                    "view": result.view_name, "theta": float(theta), "class": cls,
                    "boxes": 0, "support": 0, "support_median": np.nan,
                    "support_p95": np.nan, "confidence_mean": np.nan,
                    "width_mean": np.nan, "contraction_events": model.contraction_events_,
                })
                continue
            widths = np.mean(np.maximum(model.w_[idx] - model.v_[idx], 0.0), axis=1)
            rows.append({
                "view": result.view_name,
                "theta": float(theta),
                "class": int(cls),
                "boxes": int(len(idx)),
                "support": int(np.sum(model.support_[idx])),
                "support_median": float(np.median(model.support_[idx])),
                "support_p95": float(np.quantile(model.support_[idx], .95)),
                "confidence_mean": float(np.mean(cf[idx])),
                "confidence_p95": float(np.quantile(cf[idx], .95)),
                "width_mean": float(np.mean(widths)),
                "width_p95": float(np.quantile(widths, .95)),
                "contraction_events": int(model.contraction_events_),
            })
    return rows
