"""Feedback slots and a cross-attention decoder between BEATs frames and the ASD head.

Pass-1 logits are detached. The decoder writes a residual onto frames. That residual
is zero at initialization, and it stays zero when every slot is zero, so an empty
condition matches the frozen F12 head.
"""

import copy
import math

import torch
import torch.nn as nn
import torch.nn.functional as F

from method.frame_asd import mil_pool_logits, probs_from_logits

REASON_BOTH = 0
REASON_CRACKLE = 1
REASON_WHEEZE = 2
REASON_DISAGREE = 3
REASON_ENTROPY = 4
REASON_LOW_ENERGY = 5
REASON_OTHER = 6
REASON_MISSED_BOTH = 0
REASON_MISSED_CRACKLE = 1
REASON_MISSED_WHEEZE = 2
REASON_FALSE_WHEEZE = 3
REASON_FALSE_CRACKLE = 4
N_REASON_RULES = 7

LOW_ENERGY = 1e-4
DISAGREE_THRESHOLD = 0.2
PEAK_THRESHOLD = 0.5
S1_TAU_C = 0.91
S1_TAU_W = 0.75
W_MISSED_BOTH = 3.0
W_FALSE_WHEEZE = 2.0
W_MISSED_CRACKLE = 2.0
W_MISSED_WHEEZE = 1.5
KEY_DROP = 0.1
ENTROPY_GATE = 1.25
ENTROPY_LAYER_MARGIN = 0.25
FOUR_CLASS_NAMES = ('normal', 'crackle', 'wheeze', 'both')


def _binary_entropy(p):
    p = p.clamp(1e-6, 1.0 - 1e-6)
    return -(p * p.log() + (1.0 - p) * (1.0 - p).log())


def _cycle_energy(energy, ref):
    """Scalar energy per cycle. A [B, T] map is averaged over frames."""
    if energy is None:
        return ref.new_zeros(ref.size(0))
    energy = energy.detach().to(device=ref.device, dtype=ref.dtype)
    if energy.dim() == 2:
        return energy.mean(dim=1)
    return energy.reshape(-1)


def feedback_stats(logit_c, logit_w, energy, topk=3):
    """Nine detached pass-1 summaries. [B, 9]. No cycle labels."""
    logit_c = logit_c.detach()
    logit_w = logit_w.detach()
    c_max = torch.sigmoid(mil_pool_logits(logit_c, mode='max', topk=topk))
    w_max = torch.sigmoid(mil_pool_logits(logit_w, mode='max', topk=topk))
    c_top = torch.sigmoid(mil_pool_logits(logit_c, mode='topk', topk=topk))
    w_top = torch.sigmoid(mil_pool_logits(logit_w, mode='topk', topk=topk))
    ent_c = _binary_entropy(c_max)
    ent_w = _binary_entropy(w_max)
    energy = _cycle_energy(energy, logit_c)
    return torch.stack([
        c_max, w_max, c_top, w_top,
        ent_c, ent_w,
        (c_max - c_top).abs(), (w_max - w_top).abs(),
        energy,
    ], dim=-1)


def four_class_probs(p_c, p_w):
    """Detached pass-1 MIL probabilities as a normalized four-class distribution.

    normal (1-pc)(1-pw), crackle pc(1-pw), wheeze (1-pc)pw, both pc*pw.
    """
    p_c = p_c.detach().reshape(-1).float().clamp(0.0, 1.0)
    p_w = p_w.detach().reshape(-1).to(device=p_c.device, dtype=p_c.dtype).clamp(0.0, 1.0)
    probs = torch.stack([
        (1.0 - p_c) * (1.0 - p_w),
        p_c * (1.0 - p_w),
        (1.0 - p_c) * p_w,
        p_c * p_w,
    ], dim=-1)
    return probs / probs.sum(dim=-1, keepdim=True).clamp(min=1e-8)


def four_class_entropy(probs):
    """Shannon entropy in nats of a [B, 4] distribution. Maximum is ln 4 ≈ 1.386."""
    safe = probs.clamp(min=1e-8)
    return -(safe * safe.log()).sum(dim=-1)


# ln(2): a distribution at least as spread as a fair coin over two classes.
CONFUSED_ENTROPY = math.log(2.0)


def cycle_decision(p_c, p_w, tau_c=0.5, tau_w=0.5):
    """Inspectable cycle decision from detached MIL probabilities.

    ``pred`` is the dual-threshold class (what the official score uses).
    ``entropy`` and ``margin`` describe the four-class product distribution,
    so a later stage can see a confused cycle without reading a one-hot label.
    top-2 margin is p_(1) - p_(2). Returns tensors of shape [B].
    """
    p_c = p_c.detach().reshape(-1).float()
    p_w = p_w.detach().reshape(-1).to(device=p_c.device, dtype=p_c.dtype)
    probs = four_class_probs(p_c, p_w)
    entropy = four_class_entropy(probs)
    top_vals, top_idx = torch.topk(probs, k=2, dim=-1)
    margin = top_vals[:, 0] - top_vals[:, 1]
    crackle = p_c >= float(tau_c)
    wheeze = p_w >= float(tau_w)
    pred = torch.zeros_like(p_c, dtype=torch.long)
    pred = torch.where(crackle & ~wheeze, torch.ones_like(pred), pred)
    pred = torch.where(~crackle & wheeze, torch.full_like(pred, 2), pred)
    pred = torch.where(crackle & wheeze, torch.full_like(pred, 3), pred)
    return {
        'pred': pred,
        'entropy': entropy,
        'margin': margin,
        'top1': top_idx[:, 0],
        'top2': top_idx[:, 1],
        'probs': probs,
    }


# Operating point of the stage-1 head: tau_c=0.91, tau_w=0.75.
# logit(0.93) sits just above tau_c so a near-miss can cross it.
_LOGIT_093 = math.log(0.93 / 0.07)
_LOGIT_091 = math.log(0.91 / 0.09)
_LOGIT_075 = math.log(0.75 / 0.25)


def _masked_mean(values, mask):
    mask_f = mask.to(dtype=values.dtype)
    return (values * mask_f).sum() / mask_f.sum().clamp(min=1.0)


def boundary_hinge(pooled_c, pooled_w, labels):
    """Hinge on the head the official-test entropy audit showed was deficient.

    Gates are detached, so the loss does not chase the gate. It does not smooth
    probabilities. Each term is zero when the batch has no cycles in that cell.

    - crackle positive with top-k p_c in [0.50, 0.91): the large near-threshold
      crackle→normal band. Push the crackle logit just past tau_c.
    - normal with p_c >= 0.91: low-entropy false crackles (p_c ≈ 0.94, same as
      true crackles). Push that logit down. Do not touch confident normals.
    - wheeze-only, high entropy, p_w < 0.75: confused wheeze→normal.
      A symmetric push-down on false wheeze was measured and removed: two
      epochs dropped wheeze recall from 66% to 43% and the score by 0.16.
    - both, wheeze already on, p_c < 0.91: both→wheeze. Push crackle only.
    """
    labels = labels.detach().reshape(-1).to(device=pooled_c.device).long()
    pooled_c = pooled_c.reshape(-1)
    pooled_w = pooled_w.reshape(-1).to(device=pooled_c.device, dtype=pooled_c.dtype)
    y_c = ((labels == 1) | (labels == 3)).to(dtype=pooled_c.dtype)
    y_w = ((labels == 2) | (labels == 3)).to(dtype=pooled_c.dtype)
    p_c = torch.sigmoid(pooled_c.detach())
    p_w = torch.sigmoid(pooled_w.detach())
    entropy = four_class_entropy(four_class_probs(p_c, p_w))

    near_crackle = (y_c > 0.5) & (p_c >= 0.50) & (p_c < 0.91)
    false_crackle = (y_c < 0.5) & (p_c >= 0.91)
    missed_wheeze = (
        (y_w > 0.5) & (y_c < 0.5) & (entropy >= CONFUSED_ENTROPY) & (p_w < 0.75))
    both_short = (y_c > 0.5) & (y_w > 0.5) & (p_w >= 0.50) & (p_c < 0.91)
    return (
        _masked_mean(F.relu(_LOGIT_093 - pooled_c), near_crackle)
        + _masked_mean(F.relu(pooled_c), false_crackle)
        + _masked_mean(F.relu(_LOGIT_075 - pooled_w), missed_wheeze)
        + _masked_mean(F.relu(_LOGIT_091 - pooled_c), both_short)
    )


def entropy_anchor_weights(logit_c, logit_w, mil_pool='topk', mil_topk=3):
    """Pass-1 four-class entropy divided by its batch mean.

    Logits are detached. A constant entropy batch returns ones, which
    FrameASDLoss treats as unweighted BCE.
    """
    logit_c = logit_c.detach()
    logit_w = logit_w.detach()
    p_c, p_w = probs_from_logits(logit_c, logit_w, mode=mil_pool, topk=mil_topk)
    entropy = four_class_entropy(four_class_probs(p_c, p_w))
    mean = entropy.mean()
    if not torch.isfinite(mean) or float(mean) <= 1e-8:
        return torch.ones_like(entropy)
    return entropy / mean


def entropy_class_report(entropy, labels, class_names=FOUR_CLASS_NAMES):
    """Mean entropy by true class, and top-decile share against the train base rate."""
    entropy = entropy.detach().float().cpu().reshape(-1)
    labels = labels.detach().cpu().long().reshape(-1)
    if entropy.numel() != labels.numel():
        raise ValueError('entropy and labels must have the same length')
    n = int(labels.numel())
    if n == 0:
        raise ValueError('entropy report needs at least one cycle')
    k = max(1, int(n * 0.1))
    order = torch.argsort(entropy, descending=True, stable=True)
    top = labels[order[:k]]
    mean_entropy = {}
    base_rate = {}
    top_share = {}
    enrichment = {}
    for class_id, name in enumerate(class_names):
        mask = labels == class_id
        count = int(mask.sum())
        base = count / float(n)
        base_rate[name] = base
        mean_entropy[name] = float(entropy[mask].mean()) if count else 0.0
        share = float((top == class_id).sum().item()) / float(k)
        top_share[name] = share
        enrichment[name] = (share / base) if base > 0.0 else 0.0
    mean_entropy['all'] = float(entropy.mean())
    return {
        'n': n,
        'top_k': k,
        'mean_entropy': mean_entropy,
        'base_rate': base_rate,
        'top10_share': top_share,
        'enrichment': enrichment,
    }


def _enrichment_passes(row, gate):
    return float(row['both']) > gate or float(row['crackle']) > gate


def choose_entropy_anchor(layer10, layer11, gate=ENTROPY_GATE, margin=ENTROPY_LAYER_MARGIN):
    """Choose the entropy layer. The residual and the scored head stay on layer 11.

    ``layer10`` and ``layer11`` map class name to top-decile enrichment.
    Train only when the chosen layer is enriched for both or crackle.
    """
    use_layer10 = (
        float(layer10['both']) > float(layer11['both']) + margin
        or float(layer10['crackle']) > float(layer11['crackle']) + margin
    )
    entropy_layer = 10 if use_layer10 else 11
    chosen = layer10 if use_layer10 else layer11
    layer10_passes = _enrichment_passes(layer10, gate)
    layer11_passes = _enrichment_passes(layer11, gate)
    train = _enrichment_passes(chosen, gate)
    if not layer10_passes and not layer11_passes:
        train = False
        reason = 'neither layer has both or crackle enrichment above {:.2f}'.format(gate)
    elif not train:
        reason = (
            'chosen layer {} both {:.3f} crackle {:.3f} does not exceed {:.2f}'.format(
                entropy_layer, float(chosen['both']), float(chosen['crackle']), gate)
        )
    elif use_layer10:
        reason = (
            'layer 10 enrichment exceeds layer 11 by more than {:.2f}; '
            'entropy from layer 10, frames stay on layer 11'.format(margin)
        )
    else:
        reason = 'entropy and frames stay on layer 11'
    return {
        'train': bool(train),
        'entropy_layer': entropy_layer,
        'frame_layer': 11,
        'slot_layer': 11,
        'reason': reason,
    }


def error_sample_weights(labels, p_c, p_w, tau_c=S1_TAU_C, tau_w=S1_TAU_W):
    """Per-cycle BCE weights from labels and detached pass-1 top-k probabilities.

    Priority, last assignment wins: missed wheeze, missed crackle, false wheeze, missed both.
    A probability between 0.5 and tau_c still counts as a crackle miss.
    """
    labels = labels.detach().reshape(-1).to(device=p_c.device).long()
    p_c = p_c.detach().reshape(-1)
    p_w = p_w.detach().reshape(-1).to(device=p_c.device, dtype=p_c.dtype)
    weight = torch.ones_like(p_c)
    missed_wheeze = (labels == 2) & (p_w < tau_w)
    missed_crackle = ((labels == 1) | (labels == 3)) & (p_c < tau_c)
    false_wheeze = (labels == 0) & (p_w >= tau_w)
    missed_both = (labels == 3) & ~((p_c >= tau_c) & (p_w >= tau_w))
    weight = torch.where(missed_wheeze, torch.full_like(weight, W_MISSED_WHEEZE), weight)
    weight = torch.where(missed_crackle, torch.full_like(weight, W_MISSED_CRACKLE), weight)
    weight = torch.where(false_wheeze, torch.full_like(weight, W_FALSE_WHEEZE), weight)
    weight = torch.where(missed_both, torch.full_like(weight, W_MISSED_BOTH), weight)
    return weight


def reason_targets_from_stats(stats, soft_handoff=False, entropy_gate=CONFUSED_ENTROPY):
    """Rule id in 0..6 from pass-1 stats. Highest priority is applied last.

    ``soft_handoff`` keeps a high four-class-entropy cycle on REASON_ENTROPY.
    Class-peak rules must not turn that cycle into a hard wheeze/crackle/both code.
    The default path is unchanged.
    """
    p_c = stats[:, 0]
    p_w = stats[:, 1]
    ent = 0.5 * (stats[:, 4] + stats[:, 5])
    disagree = torch.maximum(stats[:, 6], stats[:, 7])
    energy = stats[:, 8]
    target = torch.full((stats.size(0),), REASON_OTHER, dtype=torch.long, device=stats.device)
    target = torch.where(energy < LOW_ENERGY, torch.full_like(target, REASON_LOW_ENERGY), target)
    target = torch.where(ent > 0.5 * math.log(2.0), torch.full_like(target, REASON_ENTROPY), target)
    target = torch.where(disagree > DISAGREE_THRESHOLD, torch.full_like(target, REASON_DISAGREE), target)
    class_target = target
    class_target = torch.where(
        (p_w >= PEAK_THRESHOLD) & (p_w > p_c), torch.full_like(class_target, REASON_WHEEZE), class_target)
    class_target = torch.where(
        (p_c >= PEAK_THRESHOLD) & (p_c >= p_w), torch.full_like(class_target, REASON_CRACKLE), class_target)
    class_target = torch.where(
        (p_c >= PEAK_THRESHOLD) & (p_w >= PEAK_THRESHOLD), torch.full_like(class_target, REASON_BOTH), class_target)
    if soft_handoff:
        ent4 = four_class_entropy(four_class_probs(p_c, p_w))
        confused = ent4 >= float(entropy_gate)
        class_target = torch.where(
            confused, torch.full_like(class_target, REASON_ENTROPY), class_target)
    return class_target


def reason_targets_from_train(labels, stats):
    """Error id in 0..6 from the train label and detached pass-1 peaks.

    Slots stay label-free. This target is the train-set sign the readout learns.
    Disease misses outrank a low-energy tag. A normal cycle with both peaks
    high is counted as a false wheeze.
    """
    labels = labels.detach().reshape(-1).to(device=stats.device, dtype=torch.long)
    p_c = stats[:, 0]
    p_w = stats[:, 1]
    energy = stats[:, 8]
    target = torch.full((stats.size(0),), REASON_OTHER, dtype=torch.long, device=stats.device)
    target = torch.where(energy < LOW_ENERGY, torch.full_like(target, REASON_LOW_ENERGY), target)
    target = torch.where(
        (labels == 0) & (p_c >= PEAK_THRESHOLD),
        torch.full_like(target, REASON_FALSE_CRACKLE), target)
    target = torch.where(
        (labels == 0) & (p_w >= PEAK_THRESHOLD),
        torch.full_like(target, REASON_FALSE_WHEEZE), target)
    target = torch.where(
        (labels == 1) & (p_c < PEAK_THRESHOLD),
        torch.full_like(target, REASON_MISSED_CRACKLE), target)
    target = torch.where(
        (labels == 2) & (p_w < PEAK_THRESHOLD),
        torch.full_like(target, REASON_MISSED_WHEEZE), target)
    target = torch.where(
        (labels == 3) & ~((p_c >= PEAK_THRESHOLD) & (p_w >= PEAK_THRESHOLD)),
        torch.full_like(target, REASON_MISSED_BOTH), target)
    return target


def normal_anchor_loss(logit_c1, logit_w1, logit_c2, logit_w2, normal_mask):
    """MSE of pass-2 logits toward detached pass-1, averaged over normal cycles only."""
    mse = (logit_c2 - logit_c1.detach()).pow(2).mean(dim=1)
    mse = mse + (logit_w2 - logit_w1.detach()).pow(2).mean(dim=1)
    mask = normal_mask.reshape(-1).to(device=mse.device, dtype=mse.dtype)
    return (mse * mask).sum() / mask.sum().clamp(min=1.0)


def _low_entropy_weight(logit_c1, logit_w1):
    """Pass-1 confidence weight shared by consistency losses. Detached."""
    ent_c = _binary_entropy(torch.sigmoid(logit_c1.detach()))
    ent_w = _binary_entropy(torch.sigmoid(logit_w1.detach()))
    ent = 0.5 * (ent_c + ent_w).mean(dim=1)
    return (1.0 - ent / math.log(2.0)).clamp(0.0, 1.0)


def consistency_loss(logit_c1, logit_w1, logit_c2, logit_w2):
    """Pull pass 2 toward detached pass 1 when pass-1 entropy is low."""
    weight = _low_entropy_weight(logit_c1, logit_w1)
    mse = (logit_c2 - logit_c1.detach()).pow(2).mean(dim=1)
    mse = mse + (logit_w2 - logit_w1.detach()).pow(2).mean(dim=1)
    return (weight * mse).mean()


def wheeze_consistency_loss(logit_c1, logit_w1, logit_c2, logit_w2):
    """Same low-entropy weight. MSE anchors only the wheeze logit.

    logit_c2 is accepted so this can replace consistency_loss, and it is not
    part of the MSE. Pass-1 crackle entropy still enters the shared weight.
    """
    weight = _low_entropy_weight(logit_c1, logit_w1)
    mse = (logit_w2 - logit_w1.detach()).pow(2).mean(dim=1)
    return (weight * mse).mean()


class SelfFeedback(nn.Module):
    """Learned queries cross-attend to frames, shifted by detached pass-1 stats.

    A zero-init timbre projection adds the clip-mean frame vector. Key dropout and
    the log-RMS bias touch this attention only. Frames passed to the pass-2 head
    stay intact.
    """

    def __init__(self, dim, slots=4, topk=3, heads=8, key_drop=KEY_DROP):
        super().__init__()
        if dim % heads != 0:
            raise ValueError('dim {} is not divisible by heads {}'.format(dim, heads))
        self.topk = topk
        self.slots = slots
        self.heads = heads
        self.head_dim = dim // heads
        self.scale = self.head_dim ** -0.5
        self.key_drop = key_drop
        self.use_timbre = True
        self.queries = nn.Parameter(torch.randn(1, slots, dim) * 0.02)
        self.stat_proj = nn.Linear(9, dim)
        self.timbre = nn.Linear(dim, dim, bias=False)
        nn.init.zeros_(self.timbre.weight)
        self.norm_q = nn.LayerNorm(dim)
        self.norm_kv = nn.LayerNorm(dim)
        self.q = nn.Linear(dim, dim)
        self.k = nn.Linear(dim, dim)
        self.v = nn.Linear(dim, dim)
        self.out = nn.Linear(dim, dim)
        self.norm_out = nn.LayerNorm(dim)

    def _frame_bias(self, energy, n_frames, ref):
        if energy is None or energy.dim() != 2 or energy.size(-1) != n_frames:
            return None
        energy = energy.detach().to(device=ref.device, dtype=ref.dtype)
        return energy.clamp(min=1e-8).log()

    def _attend(self, query, keyvalue, energy_bias):
        batch, n_slots, _ = query.shape
        n_frames = keyvalue.size(1)
        q = self.q(query).view(batch, n_slots, self.heads, self.head_dim).transpose(1, 2)
        k = self.k(keyvalue).view(batch, n_frames, self.heads, self.head_dim).transpose(1, 2)
        v = self.v(keyvalue).view(batch, n_frames, self.heads, self.head_dim).transpose(1, 2)
        attn = torch.matmul(q, k.transpose(-2, -1)) * self.scale
        if energy_bias is not None:
            attn = attn + energy_bias.view(batch, 1, 1, n_frames)
        if self.training and self.key_drop > 0:
            drop = torch.rand(batch, n_frames, device=query.device) < self.key_drop
            attn = attn.masked_fill(drop.view(batch, 1, 1, n_frames), float('-inf'))
        attn = torch.softmax(attn, dim=-1)
        attn = torch.nan_to_num(attn, nan=0.0)
        mixed = torch.matmul(attn, v).transpose(1, 2).reshape(batch, n_slots, -1)
        return self.out(mixed)

    def forward(self, frames, logit_c, logit_w, energy=None, slot_frames=None):
        keys = frames if slot_frames is None else slot_frames
        stats = feedback_stats(logit_c, logit_w, energy, topk=self.topk)
        batch = frames.size(0)
        query = self.queries.expand(batch, -1, -1) + self.stat_proj(stats).unsqueeze(1)
        if self.use_timbre:
            query = query + self.timbre(keys.mean(dim=1)).unsqueeze(1)
        delta = self._attend(
            self.norm_q(query), self.norm_kv(keys),
            self._frame_bias(energy, keys.size(1), keys))
        return self.norm_out(query + delta), stats


class BiasFreeCrossAttention(nn.Module):
    """Cross-attention with no biases. Zero key/value rows produce a zero residual."""

    def __init__(self, dim, heads=8):
        super().__init__()
        if dim % heads != 0:
            raise ValueError('dim {} is not divisible by heads {}'.format(dim, heads))
        self.heads = heads
        self.head_dim = dim // heads
        self.scale = self.head_dim ** -0.5
        self.q = nn.Linear(dim, dim, bias=False)
        self.k = nn.Linear(dim, dim, bias=False)
        self.v = nn.Linear(dim, dim, bias=False)
        self.out = nn.Linear(dim, dim, bias=False)
        nn.init.zeros_(self.out.weight)

    def forward(self, query, keyvalue):
        batch, time, _ = query.shape
        klen = keyvalue.size(1)
        q = self.q(query).view(batch, time, self.heads, self.head_dim).transpose(1, 2)
        k = self.k(keyvalue).view(batch, klen, self.heads, self.head_dim).transpose(1, 2)
        v = self.v(keyvalue).view(batch, klen, self.heads, self.head_dim).transpose(1, 2)
        attn = torch.matmul(q, k.transpose(-2, -1)) * self.scale
        attn = attn.softmax(dim=-1)
        mixed = torch.matmul(attn, v).transpose(1, 2).reshape(batch, time, -1)
        return self.out(mixed)


class FeedbackDecoderLayer(nn.Module):
    def __init__(self, dim, heads=8):
        super().__init__()
        self.norm_slots = nn.LayerNorm(dim)
        self.norm_frames_kv = nn.LayerNorm(dim)
        self.slot_attn = nn.MultiheadAttention(dim, heads, batch_first=True)
        self.norm_frames_q = nn.LayerNorm(dim)
        self.frame_attn = BiasFreeCrossAttention(dim, heads)

    def forward(self, frames, slots, slot_frames=None):
        active = (slots.detach().abs().sum(dim=(1, 2), keepdim=True) > 0).to(dtype=slots.dtype)
        keys = frames if slot_frames is None else slot_frames
        slot_q = self.norm_slots(slots)
        frame_kv = self.norm_frames_kv(keys)
        slot_delta, _ = self.slot_attn(slot_q, frame_kv, frame_kv, need_weights=False)
        slots = slots + active * slot_delta
        frames = frames + self.frame_attn(self.norm_frames_q(frames), slots)
        return frames, slots


class FeedbackDecoder(nn.Module):
    def __init__(self, dim, layers=2, heads=8):
        super().__init__()
        self.layers = nn.ModuleList(
            FeedbackDecoderLayer(dim, heads=heads) for _ in range(layers))

    def forward(self, frames, slots, slot_frames=None):
        for layer in self.layers:
            frames, slots = layer(frames, slots, slot_frames=slot_frames)
        return frames, slots


class ReasonReadout(nn.Module):
    def __init__(self, dim, n_codes=16):
        super().__init__()
        if n_codes < N_REASON_RULES:
            raise ValueError('reason_codes must be at least {}'.format(N_REASON_RULES))
        self.proj = nn.Linear(dim, n_codes)

    def forward(self, slots):
        return self.proj(slots.mean(dim=1))


class FeedbackRefiner(nn.Module):
    """Pass-1 head, feedback slots, decoder, pass-2 head."""

    def __init__(self, dim, slots=4, layers=2, drop_p=0.2, reason_codes=16,
                 mil_topk=3, heads=8):
        super().__init__()
        self.slots = slots
        self.drop_p = drop_p
        self.self_feedback = SelfFeedback(dim, slots=slots, topk=mil_topk, heads=heads)
        self.decoder = FeedbackDecoder(dim, layers=layers, heads=heads)
        self.readout = ReasonReadout(dim, n_codes=reason_codes)
        self.conf_proj = nn.Linear(16, dim, bias=False)
        nn.init.zeros_(self.conf_proj.weight)
        self.register_buffer('confusion', torch.zeros(4, 4))
        self.use_confusion_prior = True
        self.soft_reason_handoff = False
        self.frame_layer = None
        self.slot_layer = None
        self.layer_encoder = None

    def update_confusion(self, counts):
        """Store the previous epoch's train confusion. Counts are detached."""
        counts = counts.detach().to(device=self.confusion.device, dtype=self.confusion.dtype)
        if counts.shape != self.confusion.shape:
            raise ValueError('confusion counts must be 4x4, got {}'.format(tuple(counts.shape)))
        self.confusion.copy_(counts)

    def _mix_confusion(self, slots):
        flat = self.confusion.detach().reshape(-1).to(dtype=slots.dtype)
        if float(flat.sum()) == 0.0:
            return slots
        delta = self.conf_proj(flat / flat.sum().clamp(min=1.0))
        slots = slots.clone()
        slots[:, 0, :] = slots[:, 0, :] + delta
        return slots

    def _drop_slots(self, slots):
        if not self.training or self.drop_p <= 0:
            return slots
        drop = torch.rand(slots.size(0), device=slots.device) < self.drop_p
        return slots.masked_fill(drop.view(-1, 1, 1), 0)

    def forward(self, frames, head1, head2, external_slots=None, energy=None, labels=None,
                slot_frames=None):
        was_training = head1.training
        head1.eval()
        with torch.no_grad():
            logit_c1, logit_w1 = head1(frames)
        if was_training:
            head1.train()

        if external_slots is None:
            slots, stats = self.self_feedback(
                frames, logit_c1, logit_w1, energy, slot_frames=slot_frames)
        else:
            if external_slots.shape != (frames.size(0), self.slots, frames.size(-1)):
                raise ValueError(
                    'external_slots must be [B, {}, D], got {}'.format(
                        self.slots, tuple(external_slots.shape)))
            slots = external_slots
            stats = feedback_stats(logit_c1, logit_w1, energy, topk=self.self_feedback.topk)
        slots = self._drop_slots(slots)
        if self.use_confusion_prior:
            slots = self._mix_confusion(slots)
        frames2, slots_out = self.decoder(frames, slots, slot_frames=slot_frames)
        logit_c2, logit_w2 = head2(frames2)
        codes = self.readout(slots_out)
        if labels is None:
            target = reason_targets_from_stats(
                stats, soft_handoff=self.soft_reason_handoff)
        else:
            target = reason_targets_from_train(labels, stats)
        p_c1, p_w1 = probs_from_logits(
            logit_c1, logit_w1, mode='topk', topk=self.self_feedback.topk)
        decision = cycle_decision(p_c1, p_w1, tau_c=S1_TAU_C, tau_w=S1_TAU_W)
        return {
            'logit_c': logit_c2,
            'logit_w': logit_w2,
            'logit_c1': logit_c1,
            'logit_w1': logit_w1,
            'slots': slots,
            'codes': codes,
            'reason_target': target,
            'consistency': consistency_loss(logit_c1, logit_w1, logit_c2, logit_w2),
            'reason_loss': F.cross_entropy(codes, target),
            'decision_pred': decision['pred'],
            'decision_entropy': decision['entropy'],
            'decision_margin': decision['margin'],
        }


_LEGACY_ATTN_PREFIX = 'self_feedback.attn.'
_LEGACY_QKV = ('self_feedback.q.', 'self_feedback.k.', 'self_feedback.v.', 'self_feedback.out.')


def adapt_legacy_feedback_state(state):
    """Map a saved MultiheadAttention blob onto q, k, v, and out.

    ``in_proj_*`` is the packed Q,K,V matrix of ``nn.MultiheadAttention``.
    Those values are copied into the current linears. They are not left behind
    as unexpected keys and they are not dropped.
    """
    state = dict(state)
    legacy_keys = [key for key in state if key.startswith(_LEGACY_ATTN_PREFIX)]
    if not legacy_keys:
        return state, False
    required = (
        'self_feedback.attn.in_proj_weight',
        'self_feedback.attn.in_proj_bias',
        'self_feedback.attn.out_proj.weight',
        'self_feedback.attn.out_proj.bias',
    )
    missing = [key for key in required if key not in state]
    if missing:
        raise RuntimeError('legacy SelfFeedback attention is incomplete: {}'.format(missing))
    if any(key.startswith(_LEGACY_QKV) for key in state):
        raise RuntimeError('checkpoint has both legacy attn.* and q/k/v/out')
    in_w = state.pop('self_feedback.attn.in_proj_weight').detach().clone()
    in_b = state.pop('self_feedback.attn.in_proj_bias').detach().clone()
    out_w = state.pop('self_feedback.attn.out_proj.weight').detach().clone()
    out_b = state.pop('self_feedback.attn.out_proj.bias').detach().clone()
    extra = [key for key in list(state) if key.startswith(_LEGACY_ATTN_PREFIX)]
    if extra:
        raise RuntimeError('unmapped legacy attention keys: {}'.format(extra))
    if in_w.dim() != 2 or in_w.size(0) != in_w.size(1) * 3:
        raise RuntimeError('unexpected in_proj shape {}'.format(tuple(in_w.shape)))
    if in_b.numel() != in_w.size(0):
        raise RuntimeError('in_proj bias {} does not match weight {}'.format(
            tuple(in_b.shape), tuple(in_w.shape)))
    dim = in_w.size(1)
    q_w, k_w, v_w = in_w.split(dim, dim=0)
    q_b, k_b, v_b = in_b.split(dim, dim=0)
    state['self_feedback.q.weight'] = q_w
    state['self_feedback.q.bias'] = q_b
    state['self_feedback.k.weight'] = k_w
    state['self_feedback.k.bias'] = k_b
    state['self_feedback.v.weight'] = v_w
    state['self_feedback.v.bias'] = v_b
    state['self_feedback.out.weight'] = out_w
    state['self_feedback.out.bias'] = out_b
    return state, True


def load_feedback_state_dict(refiner, state):
    """Load a feedback blob. Legacy ``attn.in_proj_*`` weights are mapped onto q/k/v/out.

    The saved checkpoint has no timbre projection. That one key may stay at its
    zero init, and timbre is turned off so the loaded attention is the whole update.
    """
    adapted, legacy = adapt_legacy_feedback_state(state)
    missing, unexpected = refiner.load_state_dict(adapted, strict=False)
    allowed = {'self_feedback.timbre.weight'} if legacy else set()
    bad = [key for key in missing if key not in allowed]
    if unexpected or bad:
        raise RuntimeError('feedback checkpoint mismatch missing {} unexpected {}'.format(
            bad, list(unexpected)))
    if legacy:
        refiner.self_feedback.use_timbre = False
        copied = int(refiner.self_feedback.q.weight.numel())
        print('legacy SelfFeedback attention mapped onto q/k/v/out ({} q weights); timbre off'.format(copied))
    return legacy


def encoder_layers(model):
    """BEATs transformer blocks, or None when this module is not a BeatsEncoder."""
    beats = getattr(model, 'beats', None)
    encoder = getattr(beats, 'encoder', None) if beats is not None else None
    layers = getattr(encoder, 'layers', None) if encoder is not None else None
    return layers


def unfreeze_encoder_tail(model, n_layers=2):
    """Train only the last n transformer blocks. Earlier blocks stay frozen."""
    layers = encoder_layers(model)
    n = int(n_layers)
    if layers is None or len(layers) == 0 or n <= 0:
        return []
    n = min(n, len(layers))
    for layer in layers[-n:]:
        for param in layer.parameters():
            param.requires_grad = True
    return [param for layer in layers[-n:] for param in layer.parameters()]


def attach_stage2(model, head, args, device):
    """Freeze pass-1 head and the encoder. Open the tail only when asked.

    The refiner and the copied pass-2 head stay trainable.
    """
    head2 = copy.deepcopy(head)
    for param in model.parameters():
        param.requires_grad = False
    for param in head.parameters():
        param.requires_grad = False
    for param in head2.parameters():
        param.requires_grad = True
    unfreeze_encoder_tail(model, n_layers=int(getattr(args, 'encoder_tail_layers', 0) or 0))
    refiner = FeedbackRefiner(
        dim=model.encoder_dim,
        slots=args.feedback_slots,
        layers=args.feedback_layers,
        drop_p=args.feedback_drop,
        reason_codes=args.reason_codes,
        mil_topk=args.mil_topk,
    ).to(device)
    refiner.soft_reason_handoff = bool(getattr(args, 'soft_reason_handoff', False))
    refiner.head2 = head2.to(device)
    return refiner
