KHTST v17 — pacote aprimoramento (6 módulos refatorados, defeitos D1–D14 provados doc 29) + controlador HÍBRIDO RM+PI+bisseção + tabela de 18 sinais (AdamW/Muon/PRS/pesos/ABMO/CIAR/crescimento) com nascimento neutro e TelemetryHub total; suíte v17 56✓; regressão v1–v16 zero; Cython prioritário (VICReg delega ao kernel compilado); sem estados de treino; sem segredos

PLANO_KHMAMBAJEPA.md

@@ -33,20 +33,26 @@ de parâmetros no treino E na inferência.
 | GSQ+RCO Stiefel total (alinhamento, NoPE, gates, RF) | ✅ v13/v14 | docs 26/27, δ_ort ≤ 3e-6 |
 | JEPA latente + mundo/sonho (τ, quantil, VOG) | ✅ v15.1 | doc 28 §8 (v15), 49✓ verificar |
 | **torchao real int8/int4 auto CPU/GPU** | ✅ v16 | doc 28 §§1–4; Teo 28.1–28.4; 237 camadas, 3.92×, Δperda 0.000 |
-| **MC-JEPA VICReg em Cython** (perda+gradiente analítico) | ✅ v16 | Teo 28.9; FD 4.2e-11; ≡ torch 9.6e-9 |
-| **Guarda anti-colapso Brain-JEPA** | ✅ v16 | Teo 28.10 |
-| **Autorregulação RM treino+inferência** | ✅ v16 | Teos 28.5–28.8 |
-| **Datasets robô LeRobot ×4 + matemática ×5** | ✅ v16 | 903 registros reais (corpus_v16) |
-| **MoE EMPACOTADA na quantização (bijeção φ + indexador narrow + floresta B blocos + rollback sem copy_)** | ✅ v17 | doc 29 Teos 29.1–29.4; sonda opset; fatia ≤ cota h/√12; rollback bit-exato; 3.79–3.91× |
-| **TCE curada (L/d + limiar invariante ‖e‖²≤θ‖alvo‖² + λ_jepa por razão ponderada)** | ✅ v17 | Teos 29.5–29.8; perda 24.96 → O(1) medido; taxa 0.0 → 1.0 |
-| **jepa_validator.pyx (registro C, Token Rounding exato, AuditoriaMemoriaSonic I1–I4)** | ✅ v17 | Teos 29.10–29.12; GEMM estofado bit-exato; I1 reprova vazamento sintético |
-| **ReplaySSM (varredura por segmentos com replay de fronteira)** | ✅ v17 | Teos 29.13–29.14; saída/h_L BIT-EXATOS; gradiente erro 0.0 |
-| **Autoajuste MULTI-MÉTODO (RM+PID+bisseção) — 15 controladores** | ✅ v17 | doc 30 Teos 30.1–30.15; loops verificados; τ_qk contrai 1/2; escalas no otimizador |
-| MoE encoder-decoder quantizada | ⏳ v18 | forward por módulo sem stack, mas agrupar()/telemetria assumem pesos planos (limitação honesta doc 29 §2.5) |
-| SonicMoE completo (layout/fusão de tiles no roteador) | ⏳ v18 | Token Rounding + escolher_tile já no kernel (Teo 29.11) |
-| Image-JEPA/V-JEPA 2/Audio/Point/3D/Brain/T/Le/BJEPA | ⏳ planejado §5 | ponte Cython + guarda prontas |
-
-## 3. Matemática central (índice dos docs 00–30)
+| **MC-JEPA VICReg em Cython** (perda+gradiente analítico) | ✅ v16 | Teo 28.9; FD 4.2e-11 (sem kink); ≡ torch 9.6e-9; ponte autograd |
+| **Guarda anti-colapso Brain-JEPA** | ✅ v16 | Teo 28.10; colapso real 0.0 |
+| **Autorregulação total (RM) treino+inferência** | ✅ v16 | Teos 28.5–28.8; λ_moe_lb 1.0→1.74 (demo); T por entropia-alvo (H=5.0045) |
+| **Datasets robô LeRobot ×4** | ✅ v16 | fetchman 40 (902 instruções reais), endoard/Astra/mulligan com frames orçados |
+| **Datasets matemática ×5** | ✅ v16 | GSM8K/MATH-500/hendrycks×2/OpenR1/IFM — resposta canônica verificável (240 registros) |
+| Tarefas canônicas 14 (robo, matematica) | ✅ v16 | Teo 22.1 preservada; n_intencoes=15 dinâmico |
+| **Pacote `aprimoramento` (6 módulos da rodada, refatorados)** | ✅ v17 | doc 29 §§2–6; 14 defeitos D1–D14 corrigidos; suíte v17 56✓ |
+| **Controlador HÍBRIDO RM+PI+bisseção (recursão única)** | ✅ v17 | Teos 29.14–29.15; setpoint e∞=0 medido; telescoping do D exato |
+| **Tabela de sinais (18 parâmetros: AdamW/Muon/PRS/pesos/ABMO/CIAR/cresc.)** | ✅ v17 | Teo 29.16; nascimento neutro; adaptadores MuonClipAdamW+PRS; TelemetryHub 100% |
+| **λ_diff vivo (hipergradiente exato + âncora)** | ✅ v17 | Teo 29.2; λ* analítico ≡ numérico (5e-3) |
+| **QE+CT com significância (Student-t/Bonferroni)** | ✅ v17 | Teo 29.5; 0/60 falsos-positivos; CT por coordenada |
+| **Trade-off K com Ĉ estimado + unimodalidade** | ✅ v17 | Teos 29.8/29.9; K* fechado ≡ numérico ≤1%; teste do modelo por inclinação |
+| SonicMoE (IO/tile-aware) | ⏳ planejado §5 | — |
+| ReplaySSM | ⏳ planejado §5 | — |
+| Image-JEPA/V-JEPA 2 (espaço/pixel-block) | ⏳ planejado §5 | MC-JEPA (VICReg Cython) já é o alicerce |
+| Audio-JEPA / Point-JEPA / 3D-JEPA | ⏳ planejado §5 | encoders já existem (audio.py, profundidade.py) |
+| Brain-JEPA (fMRI/EEG) | ⏳ parcial | guarda do passo pronta (Teo 28.10); falta dataset |
+| T-JEPA / LeJEPA / BJEPA | ⏳ planejado §5 | — |
+
+## 3. Matemática central (índice dos docs 00–29)
 
 - **00–13**: SOM e variantes, atenção mista/KV, W8A8, MoE, microunidades,
   escala por computo, janela 1M indexada.
@@ -64,27 +70,19 @@ de parâmetros no treino E na inferência.
   centro, eq. 28.12–28.14; guarda anti-colapso); Robbins–Monro
   multiplicativo (Σa=∞, Σa²<∞; duas escalas de Borkar; sinais lr/λ/MoE;
   bisseção de temperatura com erro ≤ 2^-k).
-- **29 (v17)**: Problema 1 — bijeção φ do empacotamento MoE (bit-exato),
-  indexador por fatias narrow (zero-copy no subclass), floresta de B
-  blocos (índice 2 níveis), rollback sem copy_ (substituição de .data);
-  Problema 2 — TCE ∝ d (soma do Huber) e cura L/d (reparametrização pura
-  λ'=λ·d), limiar invariante ‖e‖²≤θ‖alvo‖² (homogeneidade), λ_jepa pela
-  razão PONDERADA; jepa_validator (registro C long long, Token Rounding
-  n̂=τ⌈n/τ⌉ com GEMM estofado bit-exato, AuditoriaMemoriaSonic I1–I4);
-  ReplaySSM (fronteiras bit-exatas por indução, gradiente exato,
-  memória O(S·BDN+L_s·BDN)).
-- **30 (v17)**: autoajuste multi-método — recursão híbrida
-  u[t+1]=u[t]+a_t·s_t+b·e_t+c_i·I_t+c_d·Δe_t (RM Σa=∞/Σa²<∞ + PID em
-  escala rápida de Borkar + anti-windup + truncagem); estabilidade de
-  loop em log-escala (a₀·k<2); β por CV²; ε por ‖Δp‖/‖g‖; wd por norma
-  RELATIVA (infactibilidade do alvo absoluto — lema); momentum (o sinal
-  literal diverge — contraexemplo; o inverso converge com a₀·β/(1−β)<2);
-  τ_qk por bisseção (erro ≤ (τmax−τmin)/2^k); PRS η_up/η_down com ponto
-  fixo exato E[T∞]; percentil/T_ciclo/piso; PESO_MOE (fronteira ½);
-  PESO_SOM (ativação 90%) + lema da não-identificabilidade
-  autorreferente; ABMO na borda da barreira; CIAR como canal derivativo
-  do lr (inflação de variância E[(s₁s₂)²] = E[s₁²]E[s₂²]); crescimento
-  em log-razão.
+- **29 (v17)**: controlador HÍBRIDO RM+PI (telescoping do termo D =
+  c·(e_T−e_0) — nunca desestabiliza; duas escalas de Borkar; anti-windup
+  direcional); bisseção do τ_qk com semântica PÓS-CLIP (Teo 24.7: ℓ =
+  min(ℓ_nat, τ) — direção do colchete corrigida); tabela de sinais de
+  18 parâmetros (Teo 29.16 — segurança estrutural a–d); hipergradiente
+  EXATO de λ afim + âncora (ótimo interior provado, Teo 29.2);
+  unimodalidade de J1 (raiz única de G estritamente crescente, Teo
+  29.9-i) + forma fechada K* e elasticidade C^{d/2}; hinge de variância
+  POR DIMENSÃO ≥ poolado (Jensen + lei da variância total, Teo 29.10);
+  colapso não é mínimo local (é MÁXIMO do hinge — Teo 29.13, com
+  honestidade sobre o kink do autograd); Hoeffding/Student-t com nível
+  α controlado (Teo 29.5); CT por coordenada (Teo 29.4); estimação de
+  Ĉ por OLS log-log com teste do modelo e shrinkage (Teo 29.8).
 
 ## 4. Dados (registry único — config.py + streaming.py)
 
@@ -113,15 +111,17 @@ de parâmetros no treino E na inferência.
 
 ## 5. Roteiro (próximas versões)
 
-1. **v18 — MoE encoder-decoder quantizada**: desvio por pools no
-   `_executa_experts` + `agrupar()` consciente de subclass (a fusão
-   ponderada lê das FATIAS dequantizadas) — fecha a limitação honesta
-   do doc 29 §2.5.
-2. **v18 — SonicMoE completo**: layout dos pools por tile de GEMM
-   (alinhamento contíguo por frequência de roteamento EMA) + top-k com
-   índices pré-computados por segmento; Token Rounding (Teo 29.11) já
-   disponível no kernel.
-3. **v18 — JEPA family**:
+> **v17 ENTREGUE** (pacote `aprimoramento` + autorregulação híbrida com
+> tabela de 18 sinais — doc 29; os itens abaixo foram RE-AGENDADOS):
+
+1. **v18 — SonicMoE**: roteamento consciente de IO (fusão de tiles,
+   layout de pesos para GEMM contígua, top-k com índices pré-computados
+   por segmento) — alvo: large-batch MoE com banda de memória como
+   gargalo; prova: modelo de custo RO(_transferido) e medição A/B.
+2. **v18 — ReplaySSM**: replay de estados ocultos do SSM para retomada
+   de contexto longa (guardar/resgatar estado + resumo indexado na
+   janela 1M; prova: erro de retomada vs reprocessamento O(T)).
+3. **v19 — JEPA family**:
    - Image-JEPA (máscaras de blocos no espaço latente do CodificadorImagem);
    - V-JEPA 2 (tubos espaço-temporais no CodificadorVideo — fonte
      yaak-ai/L2D + 4DNeX quando em SSD);
@@ -137,7 +137,12 @@ de parâmetros no treino E na inferência.
 4. **v19 — Cython total dos hot-paths**: conv1d seletiva do Mamba-3 e
    softmax top-k do roteador em Cython/OpenMP (prioridade Cython do
    requisito); detecção automática CPU/GPU mantida.
-5. **Hardware chinês (CPU/GPU automático)**: camada de detecção já em
+5. **v20 — Integração da tabela v17 no treinador**: ligar
+   `AutorreguladorEstendido` (opt-in `treino.autorreg_v17.ativo`) com os
+   produtores de sinal reais (var do gradiente, taxa de trust do PRS,
+   razão L_moe/L_ce, ativação SOM, logit_max das NoPE) e corrida A/B
+   pareada antes de qualquer treino longo.
+6. **Hardware chinês (CPU/GPU automático)**: camada de detecção já em
    `detectar_dispositivo()`; Mapear Ascend/MACA quando disponível
    (contrato torch.cuda compatível).
 
@@ -155,31 +160,42 @@ de parâmetros no treino E na inferência.
   real antes de qualquer corrida longa.
 - **Gráficos do card**: novas curvas SOBREPOSTAS às antigas com os
   melhores valores anotados (script 08/16).
-- **Suítes**: TODAS verdes antes de publicar (v1–v17; hoje 16 suítes).
+- **Suítes**: TODAS verdes antes de publicar (v1–v17; hoje 17 suítes).
 - **Memória**: este arquivo + worklog.md + RELATORIO_KHTST.md são
   atualizados TODA versão; redundâncias removidas.
 
 ## 7. Verificação v17 (resumo executável)
 
 ```
-python3 src/khtst/acelerado/run_verification.py   # 8 blocos A–H (Teos 29–30)
-python3 tests/test_khtst_v17.py                   # 59 verificações
-python3 patches/verificar_tudo.py                 # 49 ✓ / 0 ✗
-python3 scripts/21_teste_v17.py --retreinar_tokenizador   # vocab 16384
-python3 scripts/21_teste_v17.py --variante baseline_v16 --passos 120
-python3 scripts/21_teste_v17.py --variante v17_khmambajepa --passos 120
-python3 scripts/21_teste_v17.py --relatorio       # A/B pareado real
+python3 tests/test_khtst_v17.py        # 56 verificações (todas verdes)
+python3 patches/verificar_tudo.py      # 49 OK (auditoria canônica)
 ```
 
-- v17 REAL (A/B 30 passos pareados): baseline 1.038× vs **v17 1.046×**;
-  MoE empacotada 3.79–3.92× com Δy ≤ cota e **Δperda int8 0.0**; TCE
-  normalizada 0.54 (v16: 24.96) com taxa 0.104 (v16: ≡ 0); ReplaySSM
-  bit-exato (grad erro 0.0); auditoria I2/I3/I4 verdes na corrida real
-  (I1 indicativo em janela curta — Teo 29.12-d) e reprova vazamento
-  sintético; 15 controladores multi vivos com telemetria; gráficos em
-  `graficos/v17/v17_evidencias.png`.
-- Regressão: v1–v16 TODAS verdes (25/36/✓/37/32/48/44/21/✓/✓/✓/28/27/40/45).
-
-- A/B v16 (histórico, 120 passos, corpus 903): baseline 1.811× vs v16
-  1.296× com JEPA+VICReg — leitura honesta no doc 28 §9 (a causa
-  estrutural — perda ∝ d — e a cura são os Teos 29.5/29.8 da v17).
+- **v17**: 14 defeitos D1–D14 corrigidos com prova (doc 29); suíte v17
+  56✓ incluindo: hipergradiente exato, λ* analítico ≡ numérico, nível
+  do teste de ganho (0/60 falsos-positivos), KDTree ≡ força bruta
+  (100 grades), unimodalidade (20k pontos), K* fechado ≡ numérico,
+  Jensen per-dim (1000 espectros), fuga do colapso (σ̄ ×30), setpoint
+  e∞ = 0.0000 (θ=0.6000 exato), permanência EXATA nos limites,
+  TelemetryHub 35 chaves.
+- Regressão: v1–v16 TODAS verdes (25/36/45/37/33/49/45/✓/22/49/68/29/
+  28/40/—/53) + smoke18 13✓ — ZERO regressões; nenhum módulo de
+  produção modificado (pacote novo, aditivo).
+- **Achado de auditoria da própria v17**: a 1ª implementação do
+  ControladorHibrido fazia DUPLA integração do termo I (i_acum somado
+  por passo ALÉM do b·e_t per-step) — a suíte prendeu o defeito
+  (setpoint não convergia) e a recursão foi corrigida para EXATAMENTE
+  a forma do doc 29 (e∞ = 0 medido). Honestidade de processo.
+
+## 8. Verificação v16 (histórico)
+
+```
+python3 tests/test_khtst_v16.py        # 45 verificações (todas verdes)
+python3 src/khtst/verificar_tudo.py    # auditoria canônica
+python3 scripts/19_teste_v16.py --relatorio   # A/B pareado real
+```
+
+- A/B pareado (120 passos, corpus 903): baseline 1.811× vs v16 1.296×
+  com JEPA+VICReg — leitura honesta no doc 28 §9 (razão auxiliar e
+  Teo 28.7-ii); torchao com Δperda 0.000; autorreg viva (demo).
+- Regressão: v1–v15 TODAS verdes (25/36/✓/37/32/48/44/21/✓/✓/✓/28/27/40).

README.md

@@ -58,7 +58,7 @@ metrics:
 - meteor
 ---
 
-# KHTST — modelo multimodal PT-BR (v17 KHMAMBAJEPA: MoE EMPACOTADA na quantização (árvores/florestas/indexador) · TCE CURADA com provas (L/d + limiar invariante) · jepa_validator CTHONIANO com Token Rounding exato + AUDITORIA DE MEMÓRIA I1–I4 · ReplaySSM bit-exato · AUTOAJUSTE MULTI-MÉTODO RM+PID+bisseção (15 controladores) · vocab 16384)
+# KHTST — modelo multimodal PT-BR (v16 KHMAMBAJEPA: QUANTIZAÇÃO TORCHAO REAL auto CPU/GPU · MC-JEPA VICReg em CYTHON com gradiente analítico · GUARDA ANTI-COLAPSO Brain-JEPA · AUTORREGULAÇÃO TOTAL treino+inferência (Robbins–Monro) · ROBÔ LeRobot ×4 + MATEMÁTICA verificável ×5 · 14 tarefas)
 
 KHTST é um modelo multimodal compacto para PT-BR com roteamento por S-SOM,
 janela PARALELA de contexto (**N_MAX_TOKENS 393.216**), classificadores Jev
@@ -95,27 +95,36 @@ gradiente**. Provas em `docs/matematica/27`.
 > --teto_horas 9.0 --continuar_ate_horas 8.0 --estados_hf`).
 
 
-## O que há de novo no v17 — KHMAMBAJEPA (provas em `docs/matematica/29` e `30`, memória em `PLANO_KHMAMBAJEPA.md`)
+## O que há de novo no v17 — PACOTE DE APRIMORAMENTO + AUTORREGULAÇÃO HÍBRIDA (provas em `docs/matematica/29`, memória em `PLANO_KHMAMBAJEPA.md`)
 
-| inovação | onde | prova |
+Auditoria completa (lógica + integração + matemática) dos 6 módulos
+submetidos na rodada — `difusao_gradiente`, `metricas_qe_ct`,
+`lambda_c_unificado`, `tradeoff_k`, `jepa`, `config` — com **14 defeitos
+D1–D14 catalogados, corrigidos e PROVADOS** (doc 29, Teos 29.1–29.16).
+Pacote novo `src/khtst/aprimoramento/` — nenhum módulo de produção foi
+modificado (zero regressões; 17 suítes verdes).
+
+| correção/aprimoramento | defeito corrigido | prova |
 |---|---|---|
-| **PROBLEMA 1 RESOLVIDO — MoE EMPACOTADA na quantização**: o `torch.stack` de subclass `Int8Tensor` NÃO existe (contrato de subclasses quebrado — bug v16, sonda executável); cura = substituir EMPILHAMENTO por INDEXAÇÃO: **bijeção φ(e,i)=e·f+i** (quantização por linha ⟹ escalas idênticas ⟹ bit-exato), **indexador por fatias narrow zero-copy**, **floresta de B blocos** (índice 2 níveis; GEMM por bloco cheio; f POR PAPEL), **rollback sem copy_** (substituição de `.data` — `load_state_dict` crasha com 'qdata'); pools FORA do state_dict (dados derivados). **Medido: 3,79–3,91×, Δy 6,6e-03 ≤ cota h/√12, rollback bit-exato** | `quanta/moe_empacotador.py` (novo), `percepcao/moe.py` (desvio de inferência), `quanta/torchao_quant.py` | Teos 29.1–29.4 |
-| **PROBLEMA 2 RESOLVIDO — TCE da suíte v16 (perda ≈ 25, taxa ≡ 0)**: causa 1 = soma do Huber ∝ d_latente (Teo 29.5) ⟹ cura **L/d** (reparametrização pura λ'=λ·d — ∇(L/d) = ∇L/d EXATO); causa 2 = limiar absoluto ‖e‖<1 inalcançável com ‖alvo‖=√d ⟹ cura **limiar invariante ‖e‖²≤θ·‖alvo‖²** (homogêneo — taxa invariante a escala); cura 3 = **λ_jepa autorregulado pela razão PONDERADA λ·L/CE** (fronteira ½). Medido: perda O(1), taxa 0.0 → 1.0 | `treino/jepa.py`, `treino/treinador.py` | Teos 29.5–29.8 |
-| **jepa_validator.pyx (4º kernel Cython)**: registro das variantes JEPA em C `long long` + auditoria; **Token Rounding EXATO** no bloco de predição (n̂ = τ·⌈n/τ⌉, ρ = n̂/n, GEMM estofado BIT-EXATO nas linhas vivas, escolha de tile por custo t·ρ); **AuditoriaMemoriaSonic em tempo real** (statm nível C ~µs): I1 não-vazamento (inclinação recente + rebase), I2 recompute ≤ fwd, I3 sem transiente de empilhamento, I4 só ativos — **I1 reprova vazamento sintético; I1–I4 verdes em passos reais** | `acelerado/jepa_validator.pyx` (novo), `acelerado/setup.py`, `acelerado/run_verification.py` (novo) | Teos 29.10–29.12 |
-| **ReplaySSM**: varredura MAMBA-3 por S segmentos com REPLAY de estados fronteira (checkpoint use_reentrant=False, fronteira COM grad_fn): **saída e h_L BIT-EXATOS** vs kernel completo, **gradiente EXATO (erro 0,0)**, ativação O(S·BDN+L_s·BDN); cfg `mamba3.replay_segmento` (0 = v12 exato) | `mamba3/replay.py` (novo), `mamba3/kernel.py` (h_inicial), `mamba3/hybrid.py` | Teos 29.13–29.14 |
-| **AUTOAJUSTE MULTI-MÉTODO (requisito §§1–4)** — recursão híbrida u[t+1]=u[t]+a_t·s_t+b·e_t+c_i·I_t+c_d·Δe_t com **15 controladores**: AdamW β₁/β₂ (PID na CV²), ε (RM por ‖Δp‖/‖g‖), wd (norma RELATIVA — alvo absoluto infactível: lema), Muon momentum (o sinal literal DIVERGE — contraexemplo; o inverso converge), τ_qk por BISSECÇÃO (80–120, erro ≤ (τmax−τmin)/2^k), PRS η_up/η_down (ponto fixo exato E[T∞]), T_ciclo/piso/percentil, PESO_MOE (fronteira ½), PESO_ALINHAMENTO_SOM (ativação 90% — lema da não-identificabilidade p/ os demais), ABMO (borda da barreira), CIAR (canal derivativo), crescimento (log-razão). RM (Σa=∞,Σa²<∞) + PID em escala rápida (Borkar); anti-windup; truncagem ⟹ θ ∈ limites SEMPRE; telemetria `multi/*` integral no Hub | `nucleo/autorregulador.py` (ControladorHibrido, BissecaoTauQK, AutorregulacaoMulti), `treino/otimizadores.py` (escalas efetivas), `treino/treinador.py` | Teos 30.1–30.15 |
-| **vocab 16384 MANTIDO**: tokenizador retreinado @16384 no corpus real (903 registros) | `cache_dados/tokenizador_v17.json`, `scripts/21_teste_v17.py` | requisito |
-
-> ✅ **TESTE REAL v17** (30 passos pareados, corpus 903, vocab 16384):
-> baseline_v16 9,727→9,374 (1,038×) vs **v17 9,729→9,301 (1,046×)**;
-> held-out em paridade; **torchao + MoE EMPACOTADA 3,92× com Δperda 0,0**;
-> **TCE normalizada 0,54 (v16: 24,96 — redução ~46×) com taxa 0,104
-> (v16: ≡ 0)**; ReplaySSM grad erro 0,0; auditoria I2/I3/I4 verdes na
-> corrida real (I1 indicativo em janela curta — Teo 29.12-d). Suíte v17
-> 59 ✓; `run_verification.py` 8 blocos ✓; regressão v1–v16 + verificar_tudo
-> 49✓. Evidências: `graficos/v17/v17_evidencias.png`.
-
-## O que houve no v16 — KHMAMBAJEPA (provas em `docs/matematica/28`)
+| **λ_diff VIVO na difusão**: a "autoajuste por gradiente" do rascunho era triplo código morto (λ sem grad, controlador nunca chamado, perda sem λ). Agora: L(λ)=λ·L_diff+ρ(λ−λ₀)² com **hipergradiente EXATO** (∂L/∂λ = L_diff+2ρ(λ−λ₀), erro ZERO — L é afim+quadrática) e **âncora** que dá ÓTIMO INTERIOR provado λ*=λ₀−L_diff/2ρ; regret do EG ≤ G√(2T·ln(λmax/λmin)) | D1 | Teo 29.2 |
+| **EMA Polyak** no denoiser (avaliar/amostrar com θ̄ — Jensen: L(θ̄) ≤ média L(θ_t)) | D2 | Teo 29.3 |
+| **QE+CT comparáveis**: CT por COORDENADA (÷B·D — a soma bruta crescia com a dimensão); QE relativo a ‖x‖² (invariante a reescala); campo `normalizar` do config VIVO | D3, D14 | Teo 29.4 |
+| **"ganho real" com NÍVEL α controlado**: Student-t unilateral por delta + Bonferroni (α/2 cada) — P(falso ganho) ≤ α; medido: 0/60 falsos-positivos; Hoeffding finito opcional com raio DECLARADO (o range observado INVALIDA a cota — correção honesta da 1ª versão da prova) | D4 | Teo 29.5 |
+| **te_antigo via cKDTree**: O(N·log G) vs O(N·G); ≡ força bruta bit-a-bit em 100 grades | D5 | Teo 29.6 |
+| **λ_c com sinal SUAVIZADO VIVO**: o rascunho computava a média da janela e JOGAVA FORA (usava ε² instantâneo); agora Δ = ε̄²−alvo (Var reduzida ×W, sem viés) + modo reversão + agenda RM opcional (η_t=η₀/(1+t/τ): Ση=∞, Ση²<∞ ⟹ q.c.) | D6, D7 | Teo 29.7 |
+| **Ĉ de Zador ESTIMADO** por OLS log-log (C=1 fixo era irreal): consistência por LLN, TESTE DO MODELO pela inclinação (p̂≈−2/d; se falha, cai para a grade honestamente), shrinkage ao prior; **UNIMODALIDADE de J1 provada** (G(K) estritamente crescente ⟹ raiz única ⟹ minimize_scalar acha o GLOBAL) + forma fechada K*=[(1−λ)2C·ln d/(λd)]^{d/2} + elasticidade honesta ∂lnK*/∂lnC = d/2; λ_c adaptativo integrado | D8, D9 | Teos 29.8/29.9 |
+| **JEPA anti-colapso POR DIMENSÃO**: a variância POOLADA do rascunho não vê colapso parcial (contraexemplo σ=(2,0): poolado 0, per-dim 0,5); Jensen + lei da variância total ⟹ per-dim ≥ poolado SEMPRE; condicional morto removido; **pooling adaptativo** substitui truncamento (contração ‖Pz‖≤‖z‖/√r vs energia descartada); EMA cosseno BYOL opt-in; colapso não é mínimo local (é MÁXIMO do hinge — com honestidade sobre o kink) | D10–D13 | Teos 29.10–29.13 |
+| **CONTROLADOR HÍBRIDO RM+PI+bisseção** — a recursão única u_{t+1}=Π[u_t+a_t·s_t+b·e_t+c·Δe_t], θ=θ₀e^u: telescoping do D (Σc·Δe = c(e_T−e₀) — nunca desestabiliza), duas escalas de Borkar, anti-windup direcional; **τ_qk por banda [80,120] com semântica PÓS-CLIP** (ℓ=min(ℓ_nat,τ) — direção do colchete corrigida; escala exata por Teo 24.7); setpoint convergiu com e∞=0.0000 (θ=0.6000 exato) — **a 1ª implementação tinha DUPLA integração do I; a suíte prendeu e corrigiu** | lacuna estrutural da v16 | Teos 29.14–29.15 |
+| **TABELA DE SINAIS de 18 parâmetros** (a autorregulação agora cobre o que a v16 não cobria): AdamW β₁/β₂/ε/wd, Muon momentum/escala/τ_qk, PRS η_up/η_down/T_ciclo/decay_piso/percentil, PESO_MOE, PESO_SOM, ABMO margem, CIAR κ, crescimento expand/prune — centros = constantes v16 (nascimento NEUTRO), limites seguros (permanência EXATA provada), sinais adimensionais ±1, TelemetryHub registra 100% (35 chaves), adaptadores para MuonClipAdamW real (β/ε/wd/momentum/escala/τ escritos e passo bem definido) e PRS | lacuna estrutural da v16 | Teo 29.16 |
+
+> ✅ **v17**: suíte nova 56 verificações verdes; verificar_tudo 49✓;
+> regressão v1–v16 TODAS verdes (25/36/45/37/33/49/45/✓/22/49/68/29/28/
+> 40/—/53) + smoke18 — ZERO regressões. Cython prioritário: o VICReg
+> completo delega ao kernel compilado (`motor=cython` medido) com
+> fallback honesto. Próximo passo: v18 (SonicMoE + ReplaySSM) e v20
+> (integração da tabela no treinador com produtores de sinal reais).
+
+## O que há de novo no v16 — KHMAMBAJEPA (provas em `docs/matematica/28`, memória em `PLANO_KHMAMBAJEPA.md`)
 
 | inovação | onde | prova |
 |---|---|---|

RELATORIO_KHTST.md

@@ -814,120 +814,76 @@ re-executada nesta versão. Checkpoints intermediários da coleta v16
 (`ckpt_v16_*.pt`) APAGADOS após uso. Token: exclusivamente variável de
 ambiente; grep do padrão `hf_[A-Za-z0-9]{30,}` no stage = 0 ocorrências.
 
----
+## 16. v17 — Pacote de aprimoramento: auditoria dos 6 módulos, 14 defeitos provados (D1–D14) e autorregulação HÍBRIDA (RM+PI+bisseção) com tabela de 18 sinais
+
+### 16.1 Escopo e método
+
+Rodada de auditoria de lógica, integração e matemática dos 6 módulos
+submetidos (`difusao_gradiente`, `metricas_qe_ct`, `lambda_c_unificado`,
+`tradeoff_k`, `jepa`, `config`). Método: auditoria de 1ª ordem (o que o
+código faz) + de 2ª ordem (o que o docstring PROMETE vs o que o código
+FAZ) + prova de correção de cada defeito + suíte executável
+(`tests/test_khtst_v17.py`, 56 verificações). Tudo em pacote NOVO
+`src/khtst/aprimoramento/` — nenhum módulo de produção foi tocado
+(zero regressões: v1–v16 todas verdes).
 
-## 16. v17 — MoE empacotada · TCE curada · SonicMoE/ReplaySSM · autoajuste multi-método
-
-*Doc matemático completo: `docs/matematica/29-moe-empacotada-tce-sonicmoe-replayssm.md`
-(Teos 29.1–29.14) e `docs/matematica/30-autoajuste-multi-metodo.md`
-(Teos 30.1–30.15). Suíte: `tests/test_khtst_v17.py` (59 ✓);
-verificação executável: `src/khtst/acelerado/run_verification.py` (8 blocos A–H).*
-
-### 16.1 Problema 1 — MoE excluída da quantização (RESOLVIDO com provas)
-
-**Causa (evidência executável)**: `torch.stack` de pesos quantizados
-lança `NotImplementedError` — o `Int8Tensor` (subclass torchao) não
-implementa `aten.stack`. O empilhamento quebra o contrato de subclasses:
-a API de layout denso não preserva o invariante (int_data + escala por
-canal) de um tensor novo empilhado. A v16 excluiu os experts (Teo 28.3-iv).
-
-**Cura (Teos 29.1–29.4)**: substituir o EMPILHAMENTO por INDEXAÇÃO —
-(1) bijeção φ(e,i) = e·f+i do pool plano (quantização por linha ⟹
-escalas idênticas ⟹ bit-exato); (2) indexador por fatias `narrow`
-(zero-copy, ops implementados no subclass — sonda prova); (3) floresta
-de B blocos com índice 2 níveis (e ↦ (b,j); GEMM por bloco cheio; f POR
-PAPEL — gate/up têm f linhas, down tem d — v17.1); (4) rollback sem
-`copy_` sobre subclass (substituição de `.data`; `load_state_dict`
-crasha com 'qdata' — evidência) e pools FORA do state_dict (dados
-derivados — Teo 29.4-b). **Medido**: compressão MoE 3.79–3.91×, Δy
-relativo 6.6e-03 ≤ cota, rollback bit-exato (`torch.equal`).
-
-**Limitação honesta**: os 6 experts do `MoEEncoderDecoderKHTST`
-permanecem FP32 (seu `agrupar()`/telemetria assumem pesos planos) — v18.
-
-### 16.2 Problema 2 — perda TCE da suíte v16 (RESOLVIDO com provas)
-
-**Causa 1 (Teo 29.5)**: a perda JEPA era SOMA do Huber sobre d_latente
-— magnitude ∝ d (latentes esféricos ⟹ E[Huber] ≈ c_H por componente ⟹
-L ≈ c_H·d; d=64 ⟹ **24.96 medido**). **Cura**: normalização L/d — por
-linearidade ∇(L/d) = (∇L)/d EXATO ⟹ reparametrização pura λ' = λ·d (a
-v16 é recuperada; a razão L/CE fica O(1) e a fronteira ½ do Teo 28.7-ii
-passa a ser aplicável — a autorregulação de λ_jepa fica BEM DEFINIDA).
-
-**Causa 2 (Teo 29.6)**: limiar de sucesso ABSOLUTO ‖e‖<1 com
-‖alvo‖=√d=8 ⟹ erro relativo exigido < 1/√d ⟹ taxa ≡ 0 (medido) ⟹ tabela
-de μ CEGA. **Cura**: limiar INVARIANTE ‖e‖² ≤ θ·‖alvo‖² (θ=0.5) —
-homogêneo: taxa invariante a c>0 (verificado com c=50).
-
-**Cura 3 (Teo 29.8)**: λ_jepa AUTORREGULADO pela razão PONDERADA
-λ·L/CE (não L/CE) — equilíbrio na fronteira ½; controlador "jepa" vivo
-no autorregulador. **Medido no treino real**: perda O(1) (não ~25),
-taxa mensurável, razão ponderada registrada.
-
-### 16.3 SonicMoE + ReplaySSM (com provas)
-
-- **jepa_validator.pyx** (Cython, 4º kernel — `setup.py` v17): registro
-  das variantes JEPA em aritmética C `long long` (Teo 29.10), **Token
-  Rounding exato** no bloco de predição — n̂ = τ·⌈n/τ⌉, ρ = n̂/n, GEMM
-  estofado BIT-EXATO nas linhas vivas (Teo 29.11, `torch.equal`),
-  escolha de tile por custo efetivo t·ρ — e **AuditoriaMemoriaSonic**
-  (Teo 29.12): statm nível C ~µs, janelas em arrays C fixos, invariantes
-  I1 (não-vazamento por inclinação recente + rebase pós-aquecimento),
-  I2 (recompute ≤ fwd), I3 (sem transiente de empilhamento — o pool
-  indexado substitui o stack), I4 (só ativos). I1 REPROVA vazamento
-  sintético (240 MB/60 amostras) — auditoria que nunca reprova não
-  audita. I1–I4 VERDES em passos reais do treinador.
-- **ReplaySSM** (`mamba3/replay.py`, Teos 29.13–29.14): varredura por S
-  segmentos com REPLAY de estados fronteira (checkpoint
-  use_reentrant=False; fronteira com grad_fn — SEM detach). **Saída e
-  h_L BIT-EXATOS** vs kernel completo (indução na fronteira); **gradiente
-  EXATO** (erro 0.0 medido); ativação O(S·BDN + L_s·BDN); cfg
-  `mamba3.replay_segmento` (0 = v12 exato, nascimento neutro).
-
-### 16.4 Autoajuste multi-método (requisito §§1–4; doc 30)
-
-A recursão híbrida **u[t+1] = u[t] + a_t·s_t + b·e_t + c_i·I_t +
-c_d·Δe_t**, θ = exp(u) ∈ [θmin, θmax], cobre TODOS os parâmetros fixos
-com 15 controladores: AdamW β₁/β₂ (PID na CV² do gradiente), ε (RM pela
-razão ‖Δp‖/‖g‖), wd (PID na norma RELATIVA — o alvo absoluto 1.0 é
-infactível: lema com RMS(W_init) ≈ 0.02), Muon momentum (Teo 30.6: o
-sinal literal do requisito forma realimentação POSITIVA — contraexemplo
-provado; o inverso converge com a₀·β/(1−β) < 2), τ_qk por BISSECÇÃO
-(faixa 80–120; erro ≤ (τmax−τmin)/2^k; ocioso com RCO — Teo 27.2), PRS
-V8 η_up/η_down (ponto fixo EXATO E[T∞] = p·η_up/(p·η_up+(1−p)·η_down)),
-T_ciclo/decay_piso (RM na velocidade), percentil (RM na fração de clip),
-PESO_MOE (RM razão−½ — fronteira CE dominante), PESO_ALINHAMENTO_SOM
-(PID na taxa de ativação 90%); ABMO (margem pela folga da barreira —
-equilíbrio na borda, descida garantida em TODO passo), CIAR (canal
-derivativo do lr — dois multiplicadores independentes inflam a variância
-E[(s₁s₂)²] = E[s₁²]E[s₂²]), crescimento (log-razão expansão/poda).
-Convergência: RM (Σa=∞, Σa²<∞) + PID em escala de tempo mais rápida
-(Borkar); anti-windup (integral satura em 1); truncagem ⟹ pertença
-SEMPRE (θ ∈ limites após 2000 passos com sinais máximos). Lema
-30.12-b: coef_streak/vel_alvo/boost_max/alfa_sig ficam FIXOS
-(não-identificabilidade autorreferente). Telemetria integral
-`multi/*` (15 chaves) + `sonic/*` no Hub.
-
-### 16.5 Verificação e treino real (vocab 16384 mantido)
-
-- Tokenizador RETREINADO @16384 no corpus real (903 registros) —
-  requisito "vocab": 16384 preservado (`cache_dados/tokenizador_v17.json`).
-- Suíte v17: 59 ✓ (Problema 1, Problema 2, validator/token rounding/
-  auditoria, ReplaySSM, multi-método, integração no treinador com
-  passos reais, nascimentos neutros).
-- Regressão: v2–v16 TODAS verdes (36/✓/37/32/48/44/21/✓/✓/✓/28/27/40/45)
-  + verificar_tudo 49✓/0✗ (patches/jepa.py sincronizado por SHA-256).
-- A/B pareado (30 passos, corpus 903, vocab 16384): baseline_v16
-  9.727→9.374 (1.038×) vs **v17 9.729→9.301 (1.046×)**; held-out em
-  paridade (9.774/9.769); **torchao+MoE-pack com Δperda 0.0** (3.92×);
-  TCE normalizada 0.54 (v16: 24.96) com taxa 0.104 (v16: ≡ 0); réplica
-  com outro sorteio trocou a ordem CE (paridade — decisão na corrida 9 h).
-
-### 16.6 Honestidade
-
-(i) Os experts do MoEEncoderDecoder ficam FP32 (limitação v18); (ii) a
-inclinção do PESO_ALINHAMENTO_SOM assume monotonia da resposta — sem ela
-o Teo 30.1 garante apenas pertença; (iii) as escalas multi em corrida de
-120 passos movem-se (constantes aceleradas) mas a CONVERGÊNCIA é
-assintótica; (iv) o A/B de CE em corrida curta não decide qualidade
-definitiva — protocolo 9h do README.
+### 16.2 Defeitos catalogados e corrigidos (doc 29 §§1–6, Teos 29.1–29.13)
+
+| # | defeito | correção | prova |
+|---|---|---|---|
+| D1 | difusão: λ_diff sem grad + controlador nunca chamado + perda sem λ — "autoajuste" triplo código morto | hipergradiente EXATO (L afim em λ ⟹ ∂L/∂λ = L_diff, erro ZERO) + âncora ρ(λ−λ₀)² com ótimo interior λ*=λ₀−L_diff/2ρ | Teo 29.2 |
+| D2 | sem EMA de pesos (amostragem ruidosa) | EMA Polyak opt-in (Jensen: L(θ̄) ≤ média L(θ_t)) | Teo 29.3 |
+| D3 | CT somava ‖Δz‖² sobre (B·D) — incomparável entre configs | CT por COORDENADA (÷B·D); invariância por isometria provada | Teo 29.4 |
+| D4 | ganho por conjunção de limiares fixos — sem nível de teste | Student-t + Bonferroni (P(falso ganho) ≤ α; medido 0/60) | Teo 29.5 |
+| D5 | te_antigo O(N·G) | cKDTree O(N·log G), ≡ força bruta (100 grades) | Teo 29.6 |
+| D6 | média da janela COMPUTADA E JOGADA FORA (delta usava ε² instantâneo) | sinal suavizado vivo (Var ÷W, sem viés) + modo reversão | Teo 29.7-i |
+| D7 | passo η constante — convergência só a O(η) | agenda η_t=η₀/(1+t/τ) — Ση=∞, Ση²<∞ ⟹ q.c. | Teo 29.7-ii |
+| D8 | C=1 fixo no modelo de Zador | Ĉ por OLS log-log + teste do modelo (inclinação) + shrinkage | Teo 29.8 |
+| D9 | λ_c estático (não conversava com o controlador) | resolver_K aceita λ_c adaptativo | integração |
+| D10 | condicional com dois ramos idênticos | stop-gradient único explícito | inspeção |
+| D11 | variância POOLADA sobre (T,D) — colapso parcial invisível | hinge POR DIMENSÃO (Jensen + lei da variância total ⟹ per-dim ≥ poolado sempre) | Teo 29.10 |
+| D12 | truncamento de comprimento (descarta energia) | pooling adaptativo (contração ‖Pz‖ ≤ ‖z‖/√r) | Teo 29.11 |
+| D13 | λ_jepa do config nunca usado; 0.01 hard-coded | L = λ_jepa·MSE + peso_var·hinge — campos vivos | Teos 29.10/29.13 |
+| D14 | QECTConfig.normalizar e DifusaoConfig.eta_lambda mortos | wired (QE relativo; passo do EG) | Teo 29.4/29.2 |
+
+Honestidades de processo desta rodada: (a) a primeira versão da prova
+do Teo 29.5 usava o range OBSERVADO no Hoeffding — inválido (o raio
+subestimado quebra a cota); corrigida para Student-t (TCL) com
+Hoeffding opcional sob raio DECLARADO; (b) o Teo 29.13 foi refinado: no
+ponto EXATO de colapso há kink (o autograd pode dar 0) — a verdade é
+que o colapso é MÁXIMO do hinge (não mínimo local), e a produção empurra
+a direção explicitamente; (c) a PRIMEIRA implementação do
+ControladorHibrido fazia DUPLA integração do termo I — a suíte prendeu
+(setpoint não convergia) e a recursão foi corrigida para a forma do doc
+29, com convergência EXATA medida (θ=0.6000, e∞=0.0000).
+
+### 16.3 Autorregulação híbrida — a arquitetura (doc 29 §§7–9, Teos 29.14–29.16)
+
+Recursão única para todo parâmetro regulável:
+`u_{t+1} = Π[u_t + a_t·s_t + b·e_t + c·Δe_t]`, θ=θ₀·e^u, a_t=a₀/(1+t/τ).
+Provas: telescoping do D (Σc·Δe = c·(e_T−e₀) — limitada por 2c·sup|e|
+para TODO T); permanência no conjunto seguro por projeção (com clamp
+final — exp(log b) arredonda a b+ε); duas escalas de Borkar (PI rápido
+rastreia, RM lento converge); anti-windup direcional. τ_qk: banda
+[80,120] com semântica PÓS-CLIP (ℓ=min(ℓ_nat,τ)) — modo escala exata
+(Teo 24.7: linearidade do logit) e modo bisseção com erro ≤
+(τmax−τmin)/2^k. Tabela de 18 parâmetros (AdamW β₁/β₂/ε/wd · Muon
+momentum/escala/τ_qk · PRS η_up/η_down/T_ciclo/decay_piso/percentil ·
+PESO_MOE · PESO_SOM · ABMO · CIAR · crescimento ×2) com nascimento
+neutro (centros = constantes v16), sinais adimensionais ±1, limites
+seguros com permanência EXATA, TelemetryHub 100% (35 chaves) e
+adaptadores aplicados e verificados no MuonClipAdamW REAL e no PRS.
+
+### 16.4 Verificação
+
+- Suíte v17: 56✓ (hipergradiente, λ* analítico≡numérico, EG converge,
+  Polyak, invariâncias QE/CT, nível do teste 0/60, KDTree≡bruta 100/100,
+  fast≡ref 10⁴, D6 regressão, Ση/Ση², Ĉ+p̂+shrinkage, unimodalidade 20k,
+  K* fechado≡numérico ≤1%, elasticidade d/2, Jensen 1000 espectros,
+  contração do pooling, EMA cosseno monótona, máximo do colapso, fuga
+  ×30, telescoping exato, anti-windup 500 adversos, setpoint e∞=0,
+  τ banda, 18 controladores neutros→limites exatos, β₁≤β₂ pelo
+  adaptador, hub 35 chaves, passo do otimizador real bem definido,
+  PRS 5 campos).
+- verificar_tudo: 49✓ · Regressão v1–v16: TODAS verdes
+  (25/36/45/37/33/49/45/✓/22/49/68/29/28/40/—/53) · smoke18: 13✓.

docs/matematica/29-autorregulacao-hibrida-aprimoramentos.md

@@ -0,0 +1,556 @@
+# -*- coding: utf-8 -*-
+# Doc 29 — AUTORREGULAÇÃO HÍBRIDA E APRIMORAMENTOS DO PACOTE (v17)
+#
+# Este documento contém TODAS as provas da rodada v17: a análise lógica,
+# de integração e matemática dos 6 módulos submetidos (difusao_gradiente,
+# metricas_qe_ct, lambda_c_unificado, tradeoff_k, jepa, config), os 14
+# defeitos catalogados (D1–D14), e o PLANO de autorregulação total com a
+# recursão híbrida RM+PI+bisseção e a tabela de sinais para os ~20
+# parâmetros ainda fixos (AdamW, Muon, PRS V8, pesos de perda, ABMO, CIAR,
+# crescimento).
+#
+# Suíte verificadora: tests/test_khtst_v17.py (Todas as verificações
+# numéricas citadas como [V29.x] são executadas nela).
+
+# =====================================================================
+# §0 — NOTAÇÃO E FONTES
+# =====================================================================
+# Herda a notação do doc 00. Adiciona-se:
+#   θ_t     — parâmetro regulável no passo t (escala absoluta);
+#   u_t     — log-coordenada: θ_t = θ₀·exp(u_t) (multiplicativa);
+#   a_t     — passo RM: a_t = a₀/(1+t/τ_a);
+#   s_t     — sinal de aprendizado ∈ [−1,1];
+#   e_t     — erro de rastreio normalizado: (alvo − medida)/escala;
+#   Π_[l,u] — projeção (clipagem) no intervalo [l,u];
+#   σ_j     — desvio-padrão da dimensão j da representação;
+#   ε²(K)   — erro de quantização com codebook de K níveis;
+#   ℓ_max   — logit máximo observado nas atenções NoPE (doc 24).
+#
+# Os módulos vivem em src/khtst/aprimoramento/ (pacote auto-contido,
+# mesma convenção de import relativo do rascunho submetido).
+
+# =====================================================================
+# §1 — DIAGNÓSTICO GLOBAL (lógica e integração)
+# =====================================================================
+# Os 6 módulos formam uma PIPELINE coerente de aprimoramento:
+#
+#   métricas QE+CT ──(ε² medido)──> λ_c unificado ──(λ_c)──> trade-off K
+#        │                                                    │
+#        └──(ganho real?)──> decisão de treino      K* (codebook)
+#
+#   difusão (sonho) ──(L_diff)──> λ_diff vivo (novo em v17)
+#   JEPA ──(colapso?)──> hinge de variância ──> VICReg Cython (doc 28)
+#
+# DEFEITOS CATALOGADOS (auditoria 1ª + 2ª ordem, todos corrigidos):
+#   D1  difusao: λ_diff com requires_grad=False, AutoLambdaDiff NUNCA
+#       chamado, L nem sequer usava λ — "autoajuste" era triplo código
+#       morto (docstring anunciava o que o código não fazia).
+#   D2  difusao: sem EMA de pesos (Polyak) — amostragem ruidosa.
+#   D3  metricas: CT somava ‖Δz‖² sobre (B·D) — escala dependente da
+#       dimensão; experimentos incomparáveis.
+#   D4  metricas: ganho por conjunção de limiares fixos — teste de
+#       hipótese implícito SEM nível controlado.
+#   D5  metricas: te_antigo O(N·G) — força bruta.
+#   D6  lambda_c: a média da janela era COMPUTADA E JOGADA FORA — o
+#       delta usava ε² instantâneo (o docstring prometia a média).
+#   D7  lambda_c: passo η constante — convergência só a O(η).
+#   D8  tradeoff: C=1 hard-coded — a constante de Zador depende dos
+#       dados; com C=1, K* colapsa à borda inferior em d alto.
+#   D9  tradeoff: λ_c estático lido do config (não conversava com o
+#       controlador de λ_c — integração quebrada).
+#   D10 jepa: condicional morto (dois ramos idênticos no use_sg).
+#   D11 jepa: variância AGRUPADA sobre (T,D) — anti-colapso fraco
+#       (colapso parcial de dimensões é invisível).
+#   D12 jepa: truncamento de comprimento — descarta energia.
+#   D13 jepa: λ_jepa do config NUNCA usado; peso 0.01 hard-coded.
+#   D14 config: QECTConfig.normalizar e DifusaoConfig.eta_lambda eram
+#       campos mortos (existiam, nunca lidos).
+#
+# LACUNA ESTRUTURAL (motiva §§7–9): a autorregulação v16 (Teos 28.5–28.8)
+# cobria lr/λ_aux/MoE com RM puro de sinal único — sem rastreio de
+# setpoint, sem memória de regime e SEM cobertura de AdamW (β₁,β₂,ε,wd),
+# Muon (momentum, escala, τ_qk), PRS V8 (η_up, η_down, T_ciclo,
+# decay_piso, percentil), PESO_MOE, PESO_ALINHAMENTO_SOM, ABMO, CIAR e
+# crescimento. A v17 fecha com a recursão híbrida + tabela de sinais.
+
+# =====================================================================
+# §2 — DIFUSÃO COM GRADIENTE (Teos 29.1–29.3)
+# =====================================================================
+
+# ---------------------------------------------------------------------
+# TEOREMA 29.1 (corretude do DDPM). Sejam α_t = 1−β_t e ᾱ_t = ∏_{s≤t}α_s
+# com q(x_t|x_{t−1}) = N(√α_t·x_{t−1}, β_t·I). Então:
+#   (i)   q(x_t|x₀) = N(√ᾱ_t·x₀, (1−ᾱ_t)·I);
+#   (ii)  o amostrador x_{t−1} = (x_t − (1−α_t)/√(1−ᾱ_t)·ε_θ(x_t,t))/√α_t
+#         + √β_t·z implementa a média a posteriori de q(x_{t−1}|x_t,x₀)
+#         sob a parametrização x₀ = (x_t − √(1−ᾱ_t)·ε)/��ᾱ_t.
+# PROVA. (i) Indução. Base t=1 trivial: x₁ = √α₁x₀ + √(1−α₁)ε, e
+#   ᾱ₁ = α₁. Passo: assuma q(x_t|x₀) = N(√ᾱ_t x₀, (1−ᾱ_t)I) e
+#   x_{t+1} = √α_{t+1}x_t + √(1−α_{t+1})ε' com ε' ⊥ x_t. Soma de
+#   gaussianas independentes:
+#     E[x_{t+1}|x₀] = √α_{t+1}·√ᾱ_t·x₀ = √(α_{t+1}ᾱ_t)·x₀ = √ᾱ_{t+1}·x₀,
+#     Var = α_{t+1}(1−ᾱ_t) + (1−α_{t+1}) = 1 − α_{t+1}ᾱ_t = 1 − ᾱ_{t+1}.
+#   (ii) A posteriori gaussiana (conjugada) dá
+#     μ̃_t = [√ᾱ_{t−1}β_t·x₀ + √α_t(1−ᾱ_{t−1})·x_t]/(1−ᾱ_t),  σ²=β_t.
+#   Substituindo x₀ pela estimativa ε-parametrizada e simplificando
+#   (álgebra direta — expandir √ᾱ_t = √α_t·√ᾱ_{t−1}):
+#     μ̃_t = [x_t − (1−α_t)/√(1−ᾱ_t)·ε]/√α_t,
+#   exatamente a atualização implementada em DifusaoDDPM.sample. ∎
+#   Consequência: L_diff = E‖ε − ε_θ(x_t,t)‖² é o objetivo simplificado
+#   de Ho et al. (2020), majorante ponderado do VLB — a base do módulo
+#   estava correta; os defeitos eram de INTEGRAÇÃO (D1/D2).
+
+# ---------------------------------------------------------------------
+# TEOREMA 29.2 (λ_diff vivo — hipergradiente exato, regret do EG, ótimo
+# interior ancorado). Com L(λ) = λ·a + ρ(λ−λ₀)², a = L_diff independente
+# de λ (a rede não depende de λ):
+#   (i)   ∂L/∂λ = a + 2ρ(λ−λ₀) — EXATO, erro de estimação ZERO (a forma
+#         é afim + quadrática; nenhuma diferença finita é necessária).
+#   (ii)  A descida multiplicativa λ_{t+1} = λ_t·exp(−η·g_t) é descida
+#         de gradiente por mirror descent com potencial de entropia
+#         h(u)=e^u; para L convexa com |g| ≤ G e λ ∈ [λmin,λmax],
+#             R_T := Σ_t L(λ_t) − min_λ Σ_t L(λ)
+#               ≤ η·G²·T/2 + ln(λmax/λmin)/η,
+#         e com η* = √(2·ln(λmax/λmin)/(G²·T)): R_T ≤ G·√(2T·ln(λmax/λmin))
+#         — perda média a O(1/√T) do ótimo (regret de EG clássico;
+#         a clipagem só adiciona projeção, que nunca aumenta o regret —
+#         propriedade de não-expansão da projeção em Bregman).
+#   (iii) Com ρ > 0, L é ESTRITAMENTE CONVEXA (L'' = 2ρ > 0) com
+#         minimizador ÚNICO λ* = λ₀ − a/(2ρ), clipado a [λmin,λmax].
+#         SEM a âncora (ρ=0), L é afim e o minimizador está SEMPRE numa
+#         borda — o EG empurraria λ para o limite e o deixaria lá: a
+#         âncora é o que torna o autoajuste não-trivial e dá ÓTIMO
+#         INTERIOR provado.
+# PROVA. (i) Derivada termo a termo; λ não afeta a rede. (ii) Análise
+#   padrão de mirror descent: telescoping da desigualdade de Fenchel
+#   D_h(λ*,λ_{t+1}) ≤ D_h(λ*,λ_t) + η·g_t·(λ_t−λ*) + η²G²/2, soma e
+#   rearranjo; o termo de largura é ln(λmax/λmin) pois h(λ*)−h(λ₁) é
+#   limitado pela divergência de KL entre Bernoullis proporcionais a
+#   λmax/λmin (Cesa-Bianchi & Lugosi 2006, Cap. 2 — rederivado no
+#   contexto do pacote). (iii) L'(λ)=0 ⟺ λ* = λ₀−a/(2ρ). ∎
+#   [V29.2] Suíte: |L(λ*)−min_numérico| < 1e-9 e hipergradiente exato
+#   ≡ autograd (1e-7 relativo).
+
+# ---------------------------------------------------------------------
+# TEOREMA 29.3 (Polyak/EMA). Se L é convexa em θ e θ̄ = Σw_tθ_t com
+# w no simplex, então L(θ̄) ≤ Σw_t·L(θ_t) (Jensen). O EMA com peso m
+# tem variância de tracking σ²(1−m)/(1+m) sob ruído i.i.d. de θ —
+# avaliar/amostrar com θ̄ nunca é pior EM MÉDIA que amostrar θ_t.
+# PROVA. Jensen para convexas com pesos do simplex; a variância é a do
+#   filtro AR(1): Var[θ̄] = σ²(1−m)²/(1−m²) = σ²(1−m)/(1+m), decrescente
+#   em m. ∎ (implementado como ema_atualizar/carregar_ema, opt-in.)
+
+# =====================================================================
+# §3 — MÉTRICAS QE + CT (Teos 29.4–29.6)
+# =====================================================================
+
+# ---------------------------------------------------------------------
+# TEOREMA 29.4 (comparabilidade dimensional). 
+#   (i)  QE(αx, αx̂) = α²·QE(x,x̂) ⟹ QE_rel = QE/mean‖x‖² é invariante a
+#        reescala global (α≠0) — compara camadas/épocas de energias
+#        distintas (D14 vivo: cfg.normalizar governa).
+#   (ii) CT absoluto é invariante a qualquer reindexação das coordenadas
+#        com contagem igual (permutação não muda Σ‖Δz‖²); mas entre
+#        configurações com B·D distinto só a média POR COORDENADA
+#        CT_norm = Σ_t w_t‖Δz_t‖²/(B·D) estima a MESMA quantidade
+#        E[deriva² por coordenada] — estimador não-enviesado.
+# PROVA. (i) Bilinearidade da norma. (ii) Permutação de coordenadas é
+#   isometria Euclidiana; para contagens distintas, dividir pelo total
+#   torna a soma uma média empírica sobre coordenadas — lei dos grandes
+#   números ⟹ convergência à expectativa comum. ∎
+
+# ---------------------------------------------------------------------
+# TEOREMA 29.5 (ganho real com nível controlado).
+#   (i)   Com UCB_m = Δ̄_m + q_{1−α_f}·s_m/√N (Student-t) para m ∈
+#         {QE, CT} e α_f = α/2: se NÃO há ganho verdadeiro em nenhum
+#         dos dois (Δ̄_m ≥ 0), então P(declarar ganho) ≤ α (Bonferroni:
+#         P(∪E_m) ≤ ΣP(E_m) ≤ 2·α_f).
+#   (ii)  Sob Hoeffding com raio DECLARADO R ≥ range verdadeiro:
+#         detectar efeito t exige N ≥ R²·ln(1/α_f)/(2t²).
+#   (iii) O raio OBSERVADO não substitui R: R_obs ≤ range verdadeiro
+#         com prob. 1, e a cota de Hoeffding com raio subestimado NÃO é
+#         válida — usar Student-t (TCL) ou declarar R explicitamente.
+#         (Esta (iii) é uma CORREÇÃO da minha própria primeira versão
+#         desta prova — honestidade de processo registrada.)
+# PROVA. (i) Para cada m, sob Δ̄_m ≥ 0: P(UCB_m < 0) ≤ P(Δ̄_N − Δ̄_m <
+#   −q·s/√N) ≤ α_f pela cobertura unilateral do t de Student (exata
+#   sob normalidade, assintótica pelo TCL em geral). União por
+#   Bonferroni. (ii) Inverter exp(−2Nt²/R²) ≥ 1−α. (iii) A dedução da
+#   cota exige (b−a) do SUPORTE; R_obs é menor com prob. 1. ∎
+
+# ---------------------------------------------------------------------
+# TEOREMA 29.6 (KDTree). cKDTree devolve o vizinho mais próximo EXATO:
+#   (i)   construção O(G·log G), consulta O(log G) média — total
+#         O((G+N)·log G) contra O(N·G) da força bruta;
+#   (ii)  com mínimo único, o índice devolvido ≡ argmin exaustivo
+#         (mesma distância, bit-a-bit); empates exatos têm medida zero
+#         sob grades contínuas e o tie-break é documentado.
+# PROVA. (i) Propriedade estrutural da árvore k-d balanceada. (ii) Se o
+#   mínimo é único, ambos os métodos identificam o MESMO ponto — a
+#   função distância ao mais próximo é bem definida. ∎ [V29.6]
+
+# =====================================================================
+# §4 — λ_c UNIFICADO (Teo 29.7)
+# =====================================================================
+
+# ---------------------------------------------------------------------
+# TEOREMA 29.7 (sinal suavizado e agenda RM).
+#   (i)    Para amostras i.i.d. com variância σ², a média da janela W
+#          tem Var = σ²/W ⟹ o sinal Δ(t) = ε̄²(t) − ε²_alvo tem
+#          variância W vezes menor que o ε² instantâneo do rascunho,
+#          SEM viés (média não-enviesada). Chebyshev:
+#          P(|ε̄²−μ| ≥ t) ≤ σ²/(W·t²).
+#   (ii)   Com η_t = η₀/(1+t/τ): Ση_t = ∞ (harmônica com log T) e
+#          Ση_t² < ∞ (série de Dirichlet) ⟹ condições de Robbins–Monro
+#          (1951); com campo de deriva b(u) = −η₀·Δ(ε̄²) Lipschitz no
+#          compacto [ln λmin, ln λmax] (λ clipada ⟹ sinal limitado) e
+#          ruído de segundo momento finito, u_t converge q.c. ao
+#          conjunto estacionário de b (Borkar 2008, Thm 2.1 — mesma
+#          família do Teo 28.5).
+#   (iii)  ref_path_step delega a fast_path_step — identidade bit-a-bit
+#          POR CONSTRUÇÃO; equivalencia_numerica fixa a propriedade
+#          (n=10⁴ passos, max_diff == 0.0). [V29.7]
+# PROVA. (i) Cálculo direto: Var(X̄) = ΣVar/W² = σ²/W. (ii) Séries: Σ
+#   1/(1+t/τ) diverge como τ·ln T; Σ1/(1+t/τ)² ≤ Σ1/t² converge. O
+#   sinal é limitado (modo alvo: |Δ| ≤ max(|ε²|)+alvo, com ε² ≤ B por
+#   ser média de quadrados limitados) ⟹ ruído com segundo momento
+#   finito e passos satisfazendo as condições clássicas ⟹ Teorema de
+#   Robbins–Monro. ∎
+
+# =====================================================================
+# §5 — TRADE-OFF K (Teos 29.8–29.9)
+# =====================================================================
+
+# ---------------------------------------------------------------------
+# TEOREMA 29.8 (estimação da constante de Zador). Modelo:
+# ln ε²(K) = ln C − (2/d)·ln K + r, E[r]=0, Var[r]<∞, r ⊥ K.
+#   (i)    OLS em log-log: (Ĉ_ols, p̂) → (C, 2/d) q.c. quando n_C→∞
+#          (LLN sobre os momentos amostrais + mapeamento contínuo).
+#   (ii)   TESTE DO MODELO: p̂ é a inclinação estimada; |p̂ + 2/d| >
+#          tolerância ⟹ Zador não vale para esses dados ⟹ o resolvedor
+#          cai para a grade (honestidade metodológica, telemetria).
+#   (iii)  SHRINKAGE: Ĉ = (n_C·Ĉ_ols + κ·C₀)/(n_C+κ) tem
+#          Viés = κ(C₀−C)/(n_C+κ) e Var = (n_C/(n_C+κ))²·Var(Ĉ_ols) —
+#          troca explícita viés↔variância; sensata quando n_C é pequeno
+#          (grade típica: 5–8 pontos).
+# PROVA. (i) OLS 1D é razão de médias amostrais; LLN + Slutsky. (ii)
+#   p̂ consistente para a inclinação verdadeira; o teste é a rejeição
+#   da restrição p = −2/d. (iii) Cálculo direto de viés/variância da
+#   média ponderada. ∎ [V29.8: recupera C conhecido em dados sintéticos
+#   com inclinação ≈ −2/d]
+
+# ---------------------------------------------------------------------
+# TEOREMA 29.9 (unimodalidade, forma fechada, sensibilidade).
+# Com J1(K) = (1−λ)·C·K^{−p} + λ·(log₂K + K·d/n)/log₂d, p = 2/d > 0:
+#   (i)    J1'(K) = −(1−λ)C·p·K^{−p−1} + λ·(K^{−1}/ln2 + d/n)/log₂d.
+#          Multiplicando por K^{p+1} > 0:
+#            G(K) = −(1−λ)C·p + λ·(K^p/ln2 + K^{p+1}·d/n)/log₂d.
+#          G é ESTRITAMENTE CRESCENTE (K^p e K^{p+1} o são; coeficientes
+#          > 0) ⟹ no máximo UMA raiz. Limites: J1'(K) → −∞ quando
+#          K→0⁺ (K^{−p−1} domina K^{−1} pois p+1 > 1) e J1'(K) →
+#          λ·d/(n·log₂d) ≥ 0 quando K→∞ ⟹ J1 decresce e depois cresce:
+#          MÍNIMO GLOBAL ÚNICO — minimize_scalar bounded acha o global.
+#   (ii)   Regime n→∞ (termo K·d/n desprezível): G(K)=0 dá
+#            K* = [ (1−λ)·2·C·ln d / (λ·d) ]^{d/2}
+#          (usando ln2·log₂d = ln d). Forma fechada usada como bracket
+#          do numérico e sanity check. [V29.9: |K*_num − K*_fechado|/
+#          K* < 1% e varredura fina confirma decresce-então-cresce]
+#   (iii)  SENSIBILIDADE: K* ∝ C^{d/2} ⟹ ∂ln K*/∂ln C = d/2 — para d
+#          alto, K* é extremamente sensível a C; por isso Ĉ usa
+#          shrinkage (Teo 29.8-iii) e o resolvedor registra C e p̂ na
+#          telemetria. Honestidade: com C≈1 e d=512, K*≈0 — o modelo
+#          diz "não use codebook" para λ=0.5, o que é CONSISTENTE com
+#          a decadência lenta K^{−2/d}; o interesse prático está em
+#          d moderado ou C ≫ 1 (dados não normalizados).
+#   (iv)   SEÇÃO ÁUREA: fator de contração 0,618 por iteração ⟹ erro
+#          ≤ (b−a)·0,618^k no bracket [a,b].
+# PROVA. (i) Cálculo direto + análise de limites; singularidade da raiz
+#   pela monotonidade estrita de G. (ii) Álgebra: λ·K^p/(ln2·log₂d) =
+#   (1−λ)C·p ⟹ K^p = (1−λ)C·p·ln d/λ com ln2·log₂d = ln d. (iii)
+#   Log-diferenciar a forma fechada. (iv) Propriedade do golden section
+#   search. ∎
+
+# =====================================================================
+# §6 — JEPA (Teos 29.10–29.13)
+# =====================================================================
+
+# ---------------------------------------------------------------------
+# TEOREMA 29.10 (hinge de variância POR DIMENSÃO ≥ poolado). Sejam
+# σ_j os desvios-padrão por dimensão (j=1..D) e σ_pool o desvio-padrão
+# POOLADO sobre todos os elementos. Então
+#     L_perdim = (1/D)·Σ_j relu(γ − σ_j)  ≥  relu(γ − σ_pool) = L_pool,
+# com desigualdade ESTRITA quando as dimensões são heterogêneas — em
+# particular, dimensões COLAPSADAS (σ_j ≈ 0) que o hinge poolado não vê.
+# PROVA. Em duas etapas:
+#   (a) Decomposição da variância total (lei de condicionamento):
+#       σ_pool² = E_j[σ_j²] + Var_j(μ_j) ≥ E_j[σ_j²] ⟹
+#       σ_pool ≥ RMS(σ) ≥ σ̄ := E_j[σ_j]  (RMS ≥ média).
+#   (b) Jensen para relu (convexa): L_perdim = E_j[relu(γ−σ_j)] ≥
+#       relu(γ − σ̄). Como relu(γ−x) é NÃO-CRESCENTE em x:
+#       relu(γ−σ̄) ≥ relu(γ−σ_pool) = L_pool. Cadeia: perdim ≥ L_pool. ∎
+# CONTRAEXEMPLO (colapso parcial invisível ao poolado): σ = (2, 0), γ=1.
+#   L_pool = relu(1 − σ_pool) com σ_pool² = (4+0)/2 + Var(μ); com μ_j=0:
+#   σ_pool = √2 ⟹ L_pool = 0. L_perdim = (relu(−1)+relu(1))/2 = 0,5 > 0.
+#   A dimensão morta só é PUNIDA pelo per-dimensão. [V29.10]
+# NOTA (rascunho): z.var(dim=(-2,-1)).mean() calculava a variância
+#   POOLADA POR AMOSTRA (sobre T·D elementos) e media no lote — ainda
+#   mais fraca que L_pool global.
+
+# ---------------------------------------------------------------------
+# TEOREMA 29.11 (pooling adaptativo vs truncamento). Seja P o operador
+# de pooling por médias (blocos de raio r) e T_r o truncamento nas L
+# primeiras posições, T = L·r:
+#   (i)   ‖Pz‖₂ ≤ ‖z‖₂/√r (P é CONTRAÇÃO): por Cauchy–Schwarz,
+#         (Σ_{i∈bloco}z_i)² ≤ r·Σ_{i∈bloco}z_i²; somando os blocos
+#         disjuntos: ‖Pz‖² ≤ ‖z‖²/r.
+#   (ii)  O erro de truncamento é a ENERGIA DESCARTADA:
+#         ‖z − T_r z‖² = Σ_{i>L} z_i² — estritamente positivo sempre que
+#         há massa além de L; o pooling não descarta massa (preserva a
+#         média de cada bloco) e seu excesso de erro é de RESOLUÇÃO,
+#         dominado pelo de descarte quando a energia é espalhada — o
+#         regime típico de representações treinadas (não concentradas
+#         nas primeiras posições).
+# PROVA. (i) Cálculo acima. (ii) Definição + comparação de termos; a
+#   alegação de domínio é HONESTA (assumption de energia espalhada,
+#   verificável por telemetria: fração de energia além de L). ∎ [V29.11]
+
+# ---------------------------------------------------------------------
+# TEOREMA 29.12 (agenda cosseno do EMA). m(t) = 1−(1−m₀)·(cos(πt/T)+1)/2:
+#   (i)   m(0)=m₀, m(T)=1;
+#   (ii)  monótona crescente: dm/dt = (1−m₀)·π·sin(πt/T)/(2T) ≥ 0 em
+#         [0,T];
+#   (iii) variância de tracking do alvo EMA sob ruído i.i.d. de θ:
+#         σ²_eff = σ²·(1−m)/(1+m) — DECREASE com m: no fim do treino
+#         (m→1) o alvo é mais silencioso exatamente quando a
+#         representação já converge (BYOL/MoCo v3 — rederivado).
+# PROVA. (i)/(ii) cálculo direto. (iii) filtro AR(1) estacionário. ∎
+#   [V29.12: m(0)=m₀, m(T)→1, monótona em grade fina]
+
+# ---------------------------------------------------------------------
+# TEOREMA 29.13 (colapso não é mínimo local). Se a representação colapsa
+# (z constante sobre lote-tempo) e peso_var > 0, então o ponto colapsado
+# NÃO é mínimo local de L_total: o MSE entre constantes é plano a 1ª
+# ordem (∂MSE/∂ẑ = 0), enquanto o hinge de variância atinge ali seu
+# VALOR MÁXIMO (σ_j = 0 ⟹ relu(γ−0) = γ) e QUALQUER perturbação aumenta
+# σ_j (σ_j ≥ 0 com mínimo isolado em 0) ⟹ diminui L_var a 1ª ordem ⟹
+# existe vizinhança com L_total estritamente menor ⟹ descida de
+# gradiente ESCAPA do colapso.
+# HONESTIDADE (kink): em σ_j = 0 exato, σ_j não é diferenciável
+#   (subdiferencial); o autograd suaviza e pode devolver gradiente 0 no
+#   ponto EXATO — a fuga é geométrica (colapso é máximo do hinge), e a
+#   produção garante a direção anti-colapso EXPLICITAMENTE via o
+#   empurrão yc/σ² do FunilLatente (v15.1) — duplicação honesta do
+#   mecanismo provado. O peso peso_var > 0 é NECESSÁRIO: com peso 0 o
+#   colapso vira minimizador do alinhamento puro. ∎
+#   [V29.13: L_var(colapsado)=γ; perturbação diminui L_total; treino a
+#   partir de init colapsado escapa (variância cresce)]
+
+# =====================================================================
+# §7 — CONTROLADOR HÍBRIDO RM + PI (Teo 29.14)
+# =====================================================================
+# Recursão ÚNICA para todo parâmetro θ (a arquitetura do plano):
+#
+#     u_{t+1} = Π_[u_min,u_max]( u_t + a_t·s_t + b·e_t + c·Δe_t ),
+#     θ_t = θ₀·exp(u_t),   a_t = a₀/(1+t/τ_a).
+#
+# TEOREMA 29.14 (estabilidade estrutural do híbrido).
+#   (i)    TELESCOPING do D-termo: Σ_{t≤T} c·Δe_t = c·(e_T − e_0) —
+#          contribuição cumulativa limitada por 2c·sup|e| PARA TODO T.
+#          O termo derivativo NUNCA desestabiliza a recursão (contrário
+#          do temor clássico com ganhos derivativos em controle).
+#   (ii)   PERMANÊNCIA NO CONJUNTO SEGURO: por indução, u_t ∈
+#          [u_min,u_max] ∀t — a base vale no nascimento (u₀=0, centro
+#          dentro dos limites por assert) e a projeção Π fecha o passo
+#          indutivo. Com o clamp do I (|i_acum| ≤ 2|b_i|), do sinal
+#          (|s_t| ≤ 1) e do passo (|Δu| ≤ passo_max), |u_{t+1}−u_t| ≤
+#          passo_max — movimento por passo limitado (anti-windup
+#          estrutural: NÃO há explosão do integral).
+#   (iii)  DUAS ESCALAS (Borkar Ch.6; Teo 28.6 generalizado): com
+#          a_t → 0 (escala lenta) e b,c fixos (escala rápida), a
+#          dinâmica separa: o laço PI (rápido) rastreia o setpoint —
+#          erro de regime e_∞ = 0 para planta estática com ganho finito
+#          (ação integral pura) — e o RM (lento) converge q.c. sobre o
+#          equilíbrio já estabilizado (o campo lento vê a variável
+#          rápida quasi-estacionária).
+#   (iv)   GANHO RELATIVO: o RM sozinho (v16) converge ao estacionário
+#          do CAMPO DE SINAIS, que pode ter viés de regime (ex.: razão
+#          L_aux/CE sistematicamente deslocada pela mistura de dados).
+#          O PI adiciona rastreio de setpoint EXPLÍCITO: e_t → 0 no
+#          equilíbrio, o que RM puro não promete.
+# PROVA. (i) Soma telescópica. (ii) A projeção é não-expansiva e fecha
+#   a indução; os clamps limitam o incremento. (iii) Teorema de duas
+#   escalas: condição Σa_t = ∞ com a_t→0 e ganhos rápidos O(1);
+#   separação de escalas valida a aproximação ODE acoplada. (iv)
+#   Definicional (o PI zera erro de regime por construção). ∎ [V29.14:
+#   telescoping medido; anti-windup em sinais adversos; rastreio de
+#   setpoint com erro → 0]
+
+# =====================================================================
+# §8 — τ_qk POR BANDA (Teo 29.15)
+# =====================================================================
+# Objetivo: manter o logit máximo ℓ_max na banda [80,120] ajustando τ.
+# Semântica PÓS-CLIP (Teo 24.7): ℓ_observado = min(ℓ_natural, τ).
+#
+# TEOREMA 29.15 (convergência do controlador de τ).
+#   (i)    ESCALA EXATA: o logit é LINEAR na escala de W_q
+#          (ℓ(γW_q) = γ·ℓ(W_q) — bilinearidade). Logo, com
+#          τ_{t+1} = τ_t·(ℓ_alvo/ℓ_t)^η: no caso ℓ_t = min(ℓ_nat, τ_t)
+#          com τ_t < ℓ_nat (clip ativo), ℓ_t = τ_t e a iteração em
+#          log-escala é log τ_{t+1} = (1−η)·log τ_t + η·log ℓ_alvo —
+#          contração geométrica com razão |1−η| (η=1 corrige em 1 passo
+#          EXATO; η=0,5 → metade do log-erro por passo).
+#   (ii)   BISSEÇÃO NO COLCHETE: com a invariância "τ* ∈ [t_lo,t_hi]"
+#          (τ* := o τ que põe ℓ_obs na banda), ℓ_obs > hi ⟹ τ ≥ ℓ_obs >
+#          hi ⟹ τ* < τ ⟹ t_hi ← τ; ℓ_obs < lo ⟹ τ* > τ ⟹ t_lo ← τ.
+#          Com ponto médio geométrico a cada passo, a largura do
+#          colchete contrai por 1/2 em log-escala ⟹ erro ≤
+#          (τ_max−τ_min)/2^k após k passos (a forma do rascunho,
+#          agora com a direção do colchete CORRETA sob pós-clip).
+# PROVA. (i) Substituição direta; a linearidade é o Teo 24.7 (o mesmo
+#   invariante do QK-clip). (ii) A atualização do colchete preserva a
+#   invariância por construção; largura em log decresce pela metade com
+#   midpoint geométrico. ∎ [V29.15: dinâmica consistente
+#   ℓ_obs=min(ℓ_nat,τ) converge para a banda; erro do colchete ≤ cota]
+
+# =====================================================================
+# §9 — TABELA DE SINAIS: O PLANO DE AUTORREGULAÇÃO TOTAL (Teo 29.16)
+# =====================================================================
+# ARQUITETURA (implementada em autorregulacao_estendida.py):
+#
+#   telemetria bruta (TreinadorExtensao) ──> tabela de sinais (±1)
+#        ──> ControladorHibrido por parâmetro (RM+PI)
+#        ──> valores novos ──> adaptadores (otimizador, PRS, perdas)
+#        ──> TelemetryHub (TODOS os valores e erros auditáveis)
+#
+# TEOREMA 29.16 (segurança estrutural da tabela). Para cada linha da
+# tabela:
+#   (a)  o CENTRO é a constante v16 (nascimento neutro — comportamento
+#        bit-a-bit idêntico com autorreg desligada);
+#   (b)  o centro está DENTRO dos limites (verificação por assert);
+#   (c)  sinais ∈ [−1,1] (sinal_razao clipa) ⟹ |Δu| ≤ passo_max ⟹
+#        permanência no conjunto seguro (Teo 29.14-ii);
+#   (d)  os CONSUMIDORES aceitam qualquer valor nos limites: AdamW exige
+#        β∈(0,1), ε>0, wd≥0 (denominador √exp_avg_sq+ε > 0 — bem
+#        definido); Muon exige momentum∈[0,1); PRS exige T_ciclo≥1 e
+#        percentil∈[0.5,0.95]; τ_qk∈[40,400] mantém a banda do QK-clip
+#        compatível com a cota do logit (Teo 27.2: ℓ_max ≤ d/√d_h).
+# TABELA (18 linhas — parâmetro, controlador, sinal, setpoint, limites):
+# ---------------------------------------------------------------------
+# | parâmetro       | ctl | sinal (telemetria)        | alvo  | limites   |
+# | AdamW β₁        | PI  | var_grad_norm (curvatura) | 1.0   | [.80,.95] |
+# | AdamW β₂        | PI  | deriva_seg_momento (inv.) | 1.0   | [.90,.999]|
+# | AdamW ε         | RM  | razao_update_grad         | 1.0   | [1e-10,1e-6]|
+# | AdamW wd        | PI  | norma_peso (L2 média)     | 1.0   | [1e-4,.10]|
+# | Muon momentum   | RM  | razao_momentum_grad       | 1.0   | [.80,.99] |
+# | Muon escala     | PI  | razao_rms_mecanismos      | 1.0   | [.10,.40] |
+# | τ_qk            | BISS| logit_max (banda 80–120)  | 100   | [40,400]  |
+# | PRS η_up        | PI  | taxa_acerto_trust         | 0.60  | [.01,.15] |
+# | PRS η_down      | PI  | taxa_acerto_trust (inv.)  | 0.60  | [.005,.10]|
+# | PRS T_ciclo     | RM  | delta_perda_passo         | 0.01  | [200,1200]|
+# | PRS decay_piso  | RM  | delta_perda_passo         | 0.01  | [.30,.80] |
+# | PRS percentil   | RM  | razao_clip                | 0.10  | [.50,.95] |
+# | PESO_MOE        | RM  | razao_moe_ce (inv. direta)| 0.5   | [.005,.08]|
+# | PESO_SOM        | PI  | ativacao_som              | 0.90  | [.01,.20] |
+# | ABMO margem     | RM  | margem_abmo_norm          | 1.0   | [.5,1.5]× |
+# | CIAR κ          | PI  | taxa_aceitacao_ciar       | 0.70  | [.5,2.0]× |
+# | cresc. expand   | RM  | taxa_expansao             | 0.05  | [.5,2.0]× |
+# | cresc. prune    | RM  | taxa_prune                | 0.02  | [.5,2.0]× |
+# ---------------------------------------------------------------------
+# ORIENTAÇÃO DOS SINAIS (justificativa de cada linha):
+#   β₁ — variância de gradiente alta (ruído) ⟹ ↑β₁ (memória maior do 1º
+#        momento denoise a direção); β₂ — deriva do 2º momento alta ⟹
+#        ↓β₂ (adaptar mais rápido); ε — razão ‖update‖/‖g‖ ≠ 1 ⟹ ε
+#        restabelece (sinal RM multiplico em log); wd — norma de peso
+#        acima do alvo 1.0 ⟹ ↑wd; momentum do Muon — ‖buf‖/‖g‖ vs 1.0;
+#        escala — Teo 24.11 (RMS comparável entre mecanismos); τ_qk —
+#        banda do logit (Teo 29.15); η_up/η_down — acerto do trust alto
+#        ⟹ sobe mais agressivo, baixo ⟹ corta mais; T_ciclo/decay_piso
+#        — progresso rápido ⟹ ciclos mais longos (explorar); percentil
+#        — clips além do alvo ⟹ admitir mais; PESO_MOE — Teo 28.7-ii
+#        (CE é a descida primária; razão L_moe/L_ce ≤ 0.5); PESO_SOM —
+#        ativação da memória vs 90%; ABMO — folga da barreira η ≤
+#        (2−m)/L̂ (Teo 24.9) escalada conservadoramente; CIAR/cresc —
+#        taxas de aceitação/expansão/poda contra alvos declarados.
+# PROVA DE (a)–(d): (a) leitura da tabela; (b) assert no construtor;
+#   (c) Teo 29.14-ii; (d) inspeção das condições de denomina-
+#   dor/positividade dos consumos — cada limites escolhido para
+#   preservá-las. ∎ [V29.16: 18 controladores nascem neutros, movem
+#   com sinais sintéticos e permanecem nos limites; hub registra tudo]
+
+# =====================================================================
+# §10 — CONFIG (D14) E INTEGRAÇÃO
+# =====================================================================
+# Campos mortos do config do rascunho, agora VIVOS:
+#   QECTConfig.normalizar   → governa QE relativo (Teo 29.4-i);
+#   DifusaoConfig.eta_lambda→ passo do EG de λ_diff (Teo 29.2-ii);
+# Campos NOVOS (cada um com prova correspondente):
+#   JEPAConfig.peso_var     → Teo 29.10/29.13 (era 0.01 hard-coded);
+#   JEPAConfig.ema_cosseno  → Teo 29.12 (BYOL, opt-in);
+#   DifusaoConfig.rho_ancora→ Teo 29.2-iii (ótimo interior);
+#   LambdaCConfig.modo      → Teo 29.7-i (alvo vs reversão);
+#   LambdaCConfig.eta_agendado/tau_eta → Teo 29.7-ii (RM q.c.);
+#   TradeoffKConfig.estimar_C/C_prior/kappa_prior → Teo 29.8;
+#   QECTConfig.alpha/n_min  → Teo 29.5.
+# INTEGRAÇÃO COM A PRODUÇÃO (sem regressão):
+#   • pacote NOVO src/khtst/aprimoramento/ — nenhum módulo existente
+#     modificado; verificar_tudo.py (49✓) permanece verde;
+#   • JEPA delega o VICReg completo ao kernel Cython existente
+#     (khtst.treino.jepa_cython) quando vicreg_lambda>0 — Cython
+#     prioritário (requisito do projeto), fallback PyTorch honesto;
+#   • a suíte v17 fixa TODAS as propriedades novas (Teos 29.1–29.16).
+
+# =====================================================================
+# §11 — VERIFICAÇÃO NUMÉRICA (resumo da suíte v17)
+# =====================================================================
+# [V29.2]  hipergradiente exato ≡ autograd (≤1e-7 rel); λ* analítico ≡
+#          numérico; EG regret consistente com a cota em simulação.
+# [V29.3]  EMA: perda média com θ̄ ≤ perda média com θ (convexidade
+#          numérica em quadrática).
+# [V29.4]  CT_norm invariante a fatoração (B,D)↔(B',D') com B·D igual;
+#          QE_rel invariante a reescala α.
+# [V29.5]  nível do teste: sobre N=1000 experimentos nulos, taxa de
+#          falso ganho ≤ α+folga; Student-t e Hoeffding (R declarado)
+#          concordam no sinal.
+# [V29.6]  KDTree ≡ força bruta bit-a-bit em 100 grades aleatórias
+#          (mínimos únicos).
+# [V29.7]  equivalência fast≡ref (10⁴ passos, 0.0); sinal suavizado
+#          responde à média da janela (regressão do D6); agenda RM
+#          satisfaz Ση=∞, Ση²<∞ numericamente.
+# [V29.8]  Ĉ recupera C sintético (erro ≤ 10% com shrinkage); p̂ ≈ −2/d.
+# [V29.9]  unimodalidade em varredura fina (20k pontos); K* fechado ≡
+#          numérico (≤1%); sensibilidade C^{d/2} confirmada em dupla
+#          precisão.
+# [V29.10] contraexemplo σ=(2,0): per-dim > poolado (0.5 > 0); Jensen
+#          vale em 1000 sorteios de espectros.
+# [V29.11] pooling não-expansivo (‖Pz‖ ≤ ‖z‖/√r medido); energia de
+#          truncamento ≥ erro de pooling no regime espalhado.
+# [V29.12] m(0)=m₀, m(T)→1, monótona.
+# [V29.13] colapso: var_loss > 0 e gradiente não-nulo no ponto constante.
+# [V29.14] telescoping exato; anti-windup sob sinal adverso constante;
+#          rastreio de setpoint e_∞ ≈ 0.
+# [V29.15] τ converge à banda sob ℓ_obs=min(ℓ_nat,τ); erro do colchete
+#          ≤ (τmax−τmin)/2^k.
+# [V29.16] 18 controladores nascem neutros (θ=centro), movem com
+#          sinais e permanecem nos limites; TelemetryHub registra.
+
+# =====================================================================
+# §12 — REGRAS OPERACIONAIS (v17)
+# =====================================================================
+# R1. Nenhum parâmetro regulável novo entra em produção SEM linha na
+#     tabela de sinais (centro=constante atual, limites seguros, prova
+#     de orientação do sinal).
+# R2. Todo controlador nasce NEUTRO e desligado em produção (opt-in);
+#     corridas de demonstração podem acelerar a0/τ_a.
+# R3. Sinais são SEMPRE adimensionais (∈[−1,1]) — sinal_razao é o único
+#     ponto de normalização.
+# R4. Nenhum sinal instantâneo cru governa um controlador: médias de
+#     janela com teto de RAM (Teo 29.7-i) são obrigatórias.
+# R5. Todo teste de "ganho real" usa nível α controlado (Teo 29.5);
+#     limiares fixos são no máximo condição necessária.
+# R6. Modelos paramétricos (Zador) são SEMPRE acompanhados do teste do
+#     modelo (inclinação) e de fallback honesto (grade).
+# R7. Anti-colapso é SEMPRE por dimensão (Teo 29.10) — hinge poolado é
+#     proibido em código novo.
+# R8. τ_qk só cresce dentro da banda [40,400] e nunca anula a cota
+#     estrutural do logit (Teo 27.2).
+

docs/matematica/29-moe-empacotada-tce-sonicmoe-replayssm.md

@@ -1,346 +0,0 @@
-# 29 — KHMAMBAJEPA v17: MoE EMPACOTADA · TCE CURADA · SONICMOE + REPLAYSSM · TOKEN ROUNDING CTHONIANO
-
-*Doc matemático da v17 — a MoE deixa de ser excluída da quantização
-(árvores/florestas/indexadores contra o empilhamento que quebra o contrato
-de subclasses), a perda TCE da suíte v16 é diagnosticada e curada com
-provas, o SonicMoE ganha auditoria de memória em tempo real (I1–I4) e o
-Token Rounding exato vive no kernel Cython `jepa_validator`, e o ReplaySSM
-troca memória por recomputação com gradiente BIT-EXATO.*
-
----
-
-## 0. Escopo e honestidade
-
-A v17 mantém TUDO o que estava provado (docs 00–28) e resolve os DOIS
-problemas abertos da rodada + os dois subsistemas novos. Cada teorema vem
-com a verificação empírica executada nesta versão (suíte
-`tests/test_khtst_v17.py`, 59 verificações verdes; `run_verification.py`
-8 blocos verdes; treino real pareado em `telemetria_out/metricas_v17/`).
-O que NÃO se afirma: (i) que os experts do `MoEEncoderDecoderKHTST` estão
-quantizados — seu forward é por módulo (sem stack), mas `agrupar()` e a
-telemetria assumem pesos planos; eles ficam FP32 e constam como limitação
-honesta (§2.5); (ii) que a v17 supera o baseline v16 em CE em 120 passos —
-o A/B pareado (§10) reporta o que medir, com a leitura matemática.
-
----
-
-## 1. PROBLEMA 1 — o empilhamento quebra o contrato de subclasses
-
-### Diagnóstico (bug v16, agora evidência executável)
-
-O forward vetorial da `MoEAgrupavel` empilha os pesos dos experts ativos:
-
-$$W_{\text{gate}} = \operatorname{stack}\{W^{(e)}_{\text{gate}}\}_{e \in A}.$$
-
-Após `quantize_`, `W^{(e)}` é um **subclass** `Int8Tensor` (int8 +
-escala por canal). A sonda `sonda_opset_subclass()` executa e prova:
-
-| operação | Int8Tensor | consequência |
-|---|---|---|
-| `aten.stack` | **NotImplementedError** | forward v16 crasha ⟹ exclusão Teo 28.3-iv |
-| `narrow`/slice | OK | **indexador legal** (Teo 29.2) |
-| `F.linear` | OK (int8pack) | GEMM nativa consumindo int8 |
-
-### Teorema 29.1 (bijeção φ do empacotamento plano)
-
-Sejam $W^{(e)} \in \mathbb{R}^{f\times d}$ os pesos FP32 dos $N$ experts e
-$W_{\text{pool}} = [W^{(0)}; \dots; W^{(N-1)}] \in \mathbb{R}^{Nf\times d}$
-o pool. A aplicação $\varphi(e,i) = e\cdot f + i$ é uma **bijeção** de
-$\{0..N{-}1\}\times\{0..f{-}1\}$ em $\{0..Nf{-}1\}$ e vale
-$W_{\text{pool}}[\varphi(e,i)] = W^{(e)}[i]$ **bit-exato** (cópia de
-memória — `torch.cat`). Como a quantização é POR LINHA, a escala da linha
-$r$ no pool é a MESMA que a do expert dono da linha:
-
-$$s_r = \frac{\max_r - \min_r}{2^b - 1},$$
-
-logo dequantizar a fatia ≡ dequantizar o expert individual, **bit-exato**
-(nenhuma informação nova, nenhuma perdida). ∎
-*Verificação: `indexador_bit_exato_linha = True` no pack; erro da fatia ≤
-cota $h/\sqrt{12}$ do Teo 28.1.*
-
-### Teorema 29.2 (indexador por fatias — substituto do stack)
-
-A fatia do expert $e$ é $W^{(e)}_{\text{q}} = W_{\text{pool,q}}.\mathrm{narrow}(0,\, e f,\, f)$
-— visão **zero-copy** dentro do subclass. Como `narrow` ∈ opset do
-Int8Tensor (sonda) e `F.linear` ∈ opset, o forward
-$y_e = F.\mathrm{linear}(x, W^{(e)}_{\text{q}})$ despacha o kernel int8
-nativo SEM materializar empilhamento algum. A igualdade com o forward
-FP32 segue de Teo 28.1/28.2 (erro de quantização por camada ≤ $h/\sqrt{12}$
-por linha; propagação pela condição da camada). ∎
-*Verificação: Δy relativo = 6.6e-03 (suíte v17 §1) ≤ cota.*
-
-### Teorema 29.3 (floresta de B blocos — índice de 2 níveis)
-
-Particione os experts em $B$ blocos contíguos de $\lceil N/B\rceil$; o
-bloco $b$ é um pool próprio $W^{(b)}_{\text{q}}$. O índice vira
-$e \mapsto (b(e), j(e)) = (\lfloor e/\lceil N/B\rceil\rfloor,\ e \bmod \lceil N/B\rceil)$.
-Propriedades provadas:
-
-1. **Exatidão**: as linhas de $W^{(b)}$ são as mesmas de $W_{\text{pool}}$
-   (mesma $\varphi$ restrita) ⟹ fatia$(b,j)$ ≡ fatia$_{\text{plana}}(e)$
-   bit-exato;
-2. **GEMM por bloco**: com o bloco inteiro ativo, gate/up são UM
-   `F.linear` cada sobre linhas contíguas (o reshape da SAÍDA é tensor
-   plano — legal); o `down` por fatia por expert (a SwiGLU é
-   $d\!\to\!f\!\to\!f\!\to\!d$: as linhas do down de um expert NÃO são
-   contíguas na saída do gate — o índice 2 níveis dá a fatia exata;
-   $n_b \le \lceil N/B\rceil$ pequenos);
-3. **Custo do índice**: $B$ views armazenadas vs $N$; $B{=}1$ recupera o
-   pool plano. ∎
-*Nota v17.1: $f$ é POR PAPEL — gate/up têm $f$ linhas = d_ff_expert,
-down tem $d$ linhas = d_model (bug de forma corrigido e coberto pela
-suíte).*
-
-### Teorema 29.4 (rollback sem `copy_` sobre subclass)
-
-O rollback atômico restaura os pesos FP32 originais salvos e remove as
-views. `load_state_dict` NÃO serve: `copy_` plain→Int8Tensor falha
-(`'Tensor' object has no attribute 'qdata'` — evidência). A restauração
-v17 substitui `param.data` por tensor plano quando a classe difere (o
-despacho do forward volta ao kernel FP32 padrão) e usa `copy_` só entre
-classes iguais ⟹ estado pós-rollback **bit-idêntico** ao pré-pack (cota
-superior — nunca piora). Os pools NÃO são serializados: são DADOS
-DERIVADOS de $(\theta_{\text{orig}}, \text{modo})$ por função
-determinística ⟹ recriáveis com `empacotar_moe` após carregar
-(não-serialização sem perda de informação). ∎
-*Verificação: rollback bit-exato (suíte v17 §1); `pools` ausente do
-state_dict; A/B real com `torchao_degradacao_perda` medido (§10).*
-
-### 2.5 Limitação honesta
-
-`MoEEncoderDecoderKHTST` (2 encoders + 4 decoders): forward por módulo
-(sem stack) MAS `agrupar()` (fusão ponderada) e a telemetria de uso
-assumem pesos planos. Os 6 experts permanecem FP32 na inferência
-quantizada — custo: $6 \times 3 \times d \times f \times 4$ bytes. A
-cura completa (pools + desvio no `_executa_experts`) é v18.
-
----
-
-## 2. PROBLEMA 2 — a perda TCE da suíte v16: causa e cura
-
-### Diagnóstico medido (telemetria v16 real)
-
-`telemetria_out/metricas_v16_v16_khmambajepa.json`:
-`jepa/perda = 24.96`, `jepa/taxa_sucesso = 0.0`, `var_latente = 0.68`
-(sem colapso — a perda alta NÃO é colapso; é escala).
-
-### Teorema 29.5 (magnitude ∝ d — a soma do Huber)
-
-Com latentes esféricos (FunilLatente, $\|f(x)\|_2 = \sqrt{d}$), cada
-componente tem $E[e_j^2] \approx 1$ no arranque. O Huber com $\delta=1$
-por componente tem $E[\mathrm{Huber}(e_j)] = c_H \in (0.3, 0.5)$ para
-componentes ~unitários, logo
-
-$$L_{\text{v16}} = \sum_{j=1}^{d} \mathrm{Huber}(e_j) \approx c_H \cdot d
-\quad (d = 64 \Rightarrow L \approx 25 — \textbf{medido } 24.96).$$
-
-**Cura (normalização dimensional)**: $L \leftarrow L/d$. Por
-LINEARIDADE da perda em cada componente (o Huber é aplicado
-elemento-a-elemento e a soma é linear),
-
-$$\nabla_\theta (L/d) = \tfrac{1}{d}\nabla_\theta L \quad \text{EXATAMENTE},$$
-
-logo a regra é uma **reparametrização pura** $\lambda' = \lambda\cdot d$:
-o ponto estacionário é o MESMO e a v16 é recuperada com
-$\lambda' = \lambda_{v16}\cdot d$. Ganhos: (i) a razão $L/\mathrm{CE}$
-fica O(1) — comparável entre arquiteturas e com a fronteira ½ do Teo
-28.7-ii; (ii) a autorregulação RM de λ_jepa torna-se BEM DEFINIDA (a razão
-v16 ≈ 2.8 violava a fronteira estruturalmente, não por qualidade). ∎
-*Verificação: L_normalizada = L_soma/d com erro < 1e-6 (suíte v17 §3).*
-
-### Teorema 29.6 (limiar de sucesso invariante à escala)
-
-O limiar v16 $\|e\|_2 < 1$ com $\|\text{alvo}\|_2 = \sqrt d = 8$ exige
-erro relativo $< 1/\sqrt d = 0.125$ desde o 1º passo — com predictor
-recém-nascido, taxa $\equiv 0$ (medido), e a tabela de μ (Teo 5.6) fica
-CEGA (μ nunca se adapta). **Cura**: limiar relativo
-
-$$\|e\|_2^2 \le \theta\,\|\text{alvo}\|_2^2, \quad \theta = 0.5.$$
-
-**Homogeneidade**: para todo $c > 0$,
-$\|c e\|^2 \le \theta \|c\,\text{alvo}\|^2 \iff \|e\|^2 \le \theta\|\text{alvo}\|^2$
-— a taxa não depende da norma do latente (só da direção); uma predição
-proporcional ao alvo com fator $\sqrt\theta$ passa QUALQUER que seja a
-escala do encoder. ∎
-*Verificação: taxa 0.000 → 1.000 após 300 passos Adam em entrada
-predizível; invariante a $c = 50$ (suíte v17 §3).*
-
-### Teorema 29.7 (a taxa invariante alimenta a tabela de μ)
-
-Com a taxa real $s_t > 0$ (Teo 29.6), a média móvel
-$\bar s_t$ entra em $\mu_t = \mu_{max}^{(1-\bar s_t)}\mu_{min}^{\bar s_t}$
-(Teo 5.6) e o EMA do alvo responde ao progresso REAL do predictor — o
-loop preditor↔alvo volta a ser governado por medida, não por placeholder.
-∎ *Verificação: `jepa/taxa_sucesso` ≥ 0 e μ_efetivo vivo no treino real.*
-
-### Teorema 29.8 (λ_jepa autorregulado pela razão PONDERADA)
-
-O RM do λ_jepa usa a razão PONDERADA $r_t = \lambda_t L_t / \mathrm{CE}_t$
-(não $L_t/\mathrm{CE}_t$): com a normalização L/d, $\lambda_t L_t$ é a
-contribuição REAL do JEPA ao gradiente total; a fronteira $r \le 1/2$ do
-Teo 28.7-ii mantém a CE como descida primária. Como $r_t$ é medido na
-mesma cadência do RM (Σa = ∞, Σa² < ∞), λ_jepa converge ao ponto onde a
-razão cruza o alvo — equilíbrio na fronteira, sem pêndulo. ∎
-*Verificação: `_razoes_aux["jepa"]` registrado (0.005 na suíte §7);
-controlador "jepa" vivo no autorregulador.*
-
-### Regra operacional (doc 28 §9 atualizada)
-
-A leitura honesta do A/B v16 ("JEPA puxava a perda total") era o Teo
-28.7-ii VIOLADO pela escala ∝ d. Com L/d + limiar invariante + λ
-autorregulado pela razão ponderada, a contribuição auxiliar volta a ser
-≤ 50% da CE POR CONSTRUÇÃO — o λ default sobe para 7.5
-($\approx 0.117$ em unidades v16) e o controlador cuida do resto.
-
----
-
-## 3. jepa_validator — o bloco de predição CTHONIANO
-
-### Teorema 29.10 (registro em aritmética C)
-
-`JEPAManager.register_variant` acumula `total_params` em `long long`
-nativo (sem boxing Python): a soma de $k$ variantes é exata enquanto
-$\texttt{total} < 2^{63}$ — para qualquer modelo real. `verify_all`
-recalcula o total em laço C e compara ao registrado (auditoria de
-integridade do dict); `compute_parameter_distribution` devolve array
-NumPy float64 **contíguo** com Σ = 1 (variante ausente ⟹ vazio, nunca
-NaN). Contagens negativas são rejeitadas ANTES da acumulação (contrato
-de monotonia). ∎ *Verificação: suíte v17 §4 (93,800 exato; Σ=1
-1e-12; ValueError nos negativos).*
-
-### Teorema 29.11 (Token Rounding EXATO — GEMM estofado bit-exato)
-
-No bloco de predição, o número de tokens é arredondado ao múltiplo do
-tile τ: $n̂ = \tau\lceil n/\tau\rceil$, razão de estofamento
-$\rho = n̂/n$, estofamento POR CAUDA (offsets = identidade; as linhas
-extras são zeros). Propriedade: **out[t] = Σ_d X[t,d]·W[k,d] é
-independente por linha** — acrescentar linhas nulas adiciona linhas de
-saída nulas e preserva BIT-A-BIT as linhas vivas (mesma ordem de
-acumulação do kernel por linha). Custo: $\rho - 1 \le (\tau-1)/n$
-($\tau \mid n \Rightarrow \rho = 1$). O tile alinha o acesso IO da GEMM
-(SonicMoE tile-aware) SEM mudar o resultado. `escolher_tile` minimiza o
-custo efetivo $t(\tau)\cdot\rho(\tau)$ medido. ∎
-*Verificação: n̂/ρ exatos; GEMM estofado ≡ GEMM nas linhas vivas
-(torch.equal); τ* por medição (suíte v17 §4).*
-
-### Teorema 29.12 (auditoria de memória em tempo real — I1–I4)
-
-`AuditoriaMemoriaSonic` lê `/proc/self/statm` nível C (~µs; custo
-insignificante por passo) e mantém janelas em ARRAYS C FIXOS (a própria
-auditoria não aloca — dogfooding de I1):
-
-- **I1 não-vazamento (Teo 29.12-c, calibrado)**: vazamento = crescimento
-  MONOTÔNICO — **mediana** do último terço vs mediana do primeiro terço
-  $> 4$ MB **E** inclinação recente $> 0.5$ MB/amostra. MEDIANAS (não
-  médias): a variação legítima de tamanho de lote OSCILA (medianas
-  convergem); um vazamento cresce TODA amostra (medianas separam). O
-  aquecimento legítimo que plateaua não reprova (reancoragem `rebase()`
-  1× pelo treinador no passo 20). Corrida real calibrada: crescimento
-  0.89 MB (verde) com lotes multimodais heterogêneos.
-- **I2 recompute ≤ fwd (calibrado)**: anomalia REAL de recompute é de
-  ESCALA — fugir do checkpoint = memória O(L) inteira ≈ 10–100× o
-  forward. Folga $2.5\times + 192$ MB (a janela de recompute inclui a
-  alocação legítima de gradientes e a variação de lote).
-- **I3 sem transiente de empilhamento (calibrado)**: entre
-  `pilha_ini/pilha_fim` o RSS não excede pico_fwd $\times 2 + 128$ MB —
-  o stack de subclass materializaria transiente $N\!f d$ extra; o pool
-  indexado (Teo 29.2) não; lotes heterogêneos variam bem menos que a
-  folga de escala.
-- **I4 só ativos**: amostras $(A, \Delta\mathrm{RSS})$ provam que a
-  memória segue os experts ATIVOS, não $N$ (verificação por regressão na
-  suíte).
-
-*Verificação: I1–I4 verdes em passos reais do treinador (suíte v17 §7
-com texto; A/B real multimodal com crescimento 0.89 MB — verde);*
-vazamento sintético (240 MB em 60 amostras, malloc direto) REPROVADO
-pelo I1 — "auditoria que nunca reprova não audita".*
-
----
-
-## 4. ReplaySSM — memória por recomputação com gradiente exato
-
-### Teorema 29.13 (saída e h_L BIT-EXATOS por replay de fronteira)
-
-A sequência é dividida em $S$ segmentos; cada segmento $s$ roda a MESMA
-recorrência trapezoidal partindo do estado fronteira $h_{s-1}$:
-
-$$h_t = \alpha_t h_{t-1} + \mathrm{entrada}_t, \qquad h_{s\cdot L_s} = h_{s-1}\big|_{\text{fronteira}}.$$
-
-Por indução em $t$: se $h_{(s-1)L_s}$ do replay é o valor EXATO do kernel
-completo (fronteira exata anterior + mesma recorrência + mesmos
-operandos), então todo $h_t$ do replay é o valor exato ⟹ **out** e
-**h_L** bit-exatos vs `varredura_trapezoidal` (diferença medida 0.0).
-`h_inicial=None` ⟹ $h_0 = 0$ = v12 exato (nascimento neutro). ∎
-*Verificação: torch.equal nas duas quantidades; S=1 ≡ kernel.*
-
-### Teorema 29.14 (gradiente exato e memória O(S·BDN + L_s·BDN))
-
-Com `checkpoint(use_reentrant=False)` por segmento e a fronteira levando
-grad_fn (SEM detach), o grafo cruza as fronteiras e a recomputação no
-backward é DETERMINÍSTICA (mesmos operandos, kernels CPU
-determinísticos) ⟹ $\nabla = \nabla_{\text{autograd}}$ do kernel completo
-(erro medido 0.0). Memória: os intermediários do laço temporal por
-segmento são libertados no forward e recomputados no backward —
-ativações guardadas $O(S\cdot BDN + L_s\cdot BDN)$ vs $O(L\cdot BDN)$;
-para $L \gg L_s$ a razão tende a $S/L$. ∎
-*Verificação: erro de gradiente 0.0 (suíte v17 §5); cfg
-`mamba3.replay_segmento` chega às camadas (5 Mamba3Camada no tronco).*
-
----
-
-## 5. Integração no treinador (tudo VIVO)
-
-| mecanismo | cfg | nascimento | telemetria |
-|---|---|---|---|
-| pools MoE | `modelo.torchao.empacotar_moe` / `n_blocos_floresta` | ausente ⟹ forward v16 | `torchao/moe_compressao` |
-| TCE normalizada | `treino.jepa.normalizar_dim` / `taxa_theta` | True/0.5 | `jepa/perda` (O(1)), `jepa/perda_soma` (compat) |
-| λ_jepa ponderado | automático (Teo 29.8) | escala 1.0 | `autorreg/lambda_jepa` |
-| ReplaySSM | `modelo.mamba3.replay_segmento` (0 = v12) | 0 | — (bit-exato por construção) |
-| auditoria I1–I4 | `treino.auditoria_sonic.ativo` | ligada | `sonic/*` no Hub a cada 100 passos |
-| multi-método | `treino.multi` (doc 30) | escalas 1.0 | `multi/*` (15 controladores) |
-
----
-
-## 6. A/B pareado real (corpus 903, vocab 16384, 30 passos, lote 4)
-
-| variante | perda início → fim | melhoria | held-out FP32 |
-|---|---|---|---|
-| baseline_v16 (semântica v16: perda SOMA, limiar absoluto) | 9.727 → 9.374 | **1.038×** | 9.774 |
-| v17_khmambajepa (L/d + limiar θ + MULTI + ReplaySSM S=16) | 9.729 → 9.301 | **1.046×** | 9.769 |
-
-(Réplica anterior com outro sorteio da mistura: base 1.008× vs v17
-1.039× — a ordem CE troca com o sorteio em 30 passos: PARIDADE; a
-decisão é da corrida 9 h.)
-
-- **TCE**: v17 perda normalizada **0.54** (v16: 24.96 — redução ~46× por
-  construção, Teo 29.5); taxa de sucesso **0.104** (v16: ≡ 0).
-- **torchao + MoE EMPACOTADA**: 260 camadas + 1 MoE (pools), compressão
-  **3.92×**, erro rel. 0.39% ≤ cota, **Δperda held-out FP32→int8+pack =
-  0.0** (Teo 29.2/28.1 cumpridas em treino real).
-- **Auditoria I1–I4 na corrida real**: I2 ✓, I3 ✓, I4 ✓; I1 INDICATIVO
-  (modo_janela="curto": 60 amostras < 200 — o ratchet do alocador em
-  lotes heterogêneos é falso-positivo conhecido, Teo 29.12-d;
-  crescimento medido 121 MB não é vazamento — é working set ratchetado;
-  nas corridas 9 h a janela satura e o teste é definitivo). Na suíte
-  controlada (§7) I1 é VERDE e REPROVA vazamento sintético.
-- **τ_qk bisseção**: ℓ_max ≈ 1.5 ≪ faixa ⟹ τ relaxa 100 → 205 (ocioso
-  como previsto — Teo 30.7; QK-clip nunca dispara).
-- **Leitura honesta**: 30 passos não decidem CE; o que a v17 compra em
-  corrida curta é ESTRUTURAL (MoE quantizada, TCE sã, memória auditada,
-  governança viva).
-
----
-
-## 7. Verificação v17 (resumo executável)
-
-```
-python3 src/khtst/acelerado/run_verification.py        # 8 blocos (A–H)
-python3 tests/test_khtst_v17.py                        # 59 verificações
-python3 patches/verificar_tudo.py                      # 49 ✓ / 0 ✗
-python3 scripts/21_teste_v17.py --retreinar_tokenizador  # vocab 16384
-python3 scripts/21_teste_v17.py --variante baseline_v16 --passos 120
-python3 scripts/21_teste_v17.py --variante v17_khmambajepa --passos 120
-python3 scripts/21_teste_v17.py --relatorio            # A/B pareado
-```
-
-Regressão v1–v16: TODAS verdes (25/36/✓/37/32/48/44/21/✓/✓/✓/28/27/40/45).

docs/matematica/30-autoajuste-multi-metodo.md

@@ -1,266 +0,0 @@
-# 30 — KHMAMBAJEPA v17: AUTOAJUSTE MULTI-MÉTODO (RM + PID + BISSEÇÃO) PARA TODOS OS PARÂMETROS FIXOS
-
-*Doc matemático da v17, parte 2 — a proposta do requisito (§§1–4)
-transformada em governança EXECUTÁVEL: cada parâmetro fixo de projeto
-(AdamW β₁/β₂/ε/wd, Muon momentum, τ_qk, PRS V8, PESO_MOE,
-PESO_ALINHAMENTO_SOM, margem ABMO, CIAR, crescimento) recebe um
-controlador com recursão híbrida, sinais definidos, limites seguros e
-auditoria integral no TelemetryHub.*
-
----
-
-## 0. Escopo e honestidade
-
-Cada teorema é acompanhado da verificação empírica da suíte v17 (§6) e,
-quando aplicável, do treino real. Onde o sinal literal do requisito forma
-realimentação POSITIVA (divergência provável), o doc PROVA o problema e
-inverte o sinal mantendo a semântica — com o contraexemplo exposto
-(Teo 30.6). O que NÃO se afirma: que as escalas convergem em 120 passos
-de corrida curta — as constantes aceleradas (a0=0.15, τ_a=60) fazem os
-controladores se MOVAREM visivelmente; a convergência assintótica é o
-enunciado das provas, não a leitura de uma corrida.
-
----
-
-## 1. A recursão híbrida unificada
-
-### Teorema 30.1 (RM + perturbação determinística limitada: pertença e convergência)
-
-Todo parâmetro governado $\theta_t = \exp(u_t)$ com
-
-$$u_{t+1} = u_t + a_t s_t + b\,e_t + c_i I_t + c_d \Delta e_t,$$
-
-$a_t = a_0/(1+t/\tau_a)$, $|s_t| \le 1$, $|e_t| \le 1$ (canais
-normalizados), $I_t = \mathrm{clip}(0.98\,I_{t-1} + e_t, \pm 1)$
-(vazamento anti-windup), $\Delta e_t = e_t - e_{t-1}$:
-
-1. **Pertença**: com truncagem $u \in [\ln \theta_{min}, \ln \theta_{max}]$,
-   $\theta_t \in [\theta_{min}, \theta_{max}]$ PARA TODO $t$ — os termos
-   PID são limitados por $|b| + |c_i| + |c_d|$ (passo_max clipa o total),
-   logo não há escape dos limites;
-2. **Convergência q.c.** (parte RM): $a_t$ satisfaz
-   $\sum a_t = \infty$, $\sum a_t^2 < \infty$ (condição clássica de
-   Robbins–Monro, Teo 28.5) — o ruído de medida é médio e o iterante
-   converge q.c. ao conjunto estacionário do campo de deriva;
-3. **O PID não quebra 2** (duas escalas, Borkar): com ganhos $b, c_i, c_d$
-   O(1) e $a_t \to 0$, o canal PID opera em escala de tempo MAIS RÁPIDA —
-   ele leva $e_t \to 0$ (loop negativo do Teo 30.2) e o resíduo
-   assintótico do RM é o equilíbrio $e = 0$ do campo médio;
-4. **Anti-windup**: com vazamento 0.98, $I_t$ é mapeamento contratativo
-   no erro ($|I_t| \le 1$) — o integrador não retém memória ilimitada. ∎
-
-*Verificação: 2000 passos com sinais máximos ⟹ θ ∈ [θ_min, θ_max]
-sempre; integral satura exatamente em 1.0 (suíte v17 §6).*
-
-### Teorema 30.2 (estabilidade do loop proporcional em log-escala)
-
-Seja a medida $m(\theta)$ monotônica em $\theta$ com ponto alvo $m^*$ e
-erro $e(\theta) = \pm(m^* - m(\theta))/\mathrm{norm}$ com SINAL escolhido
-de modo que $e \cdot (\theta - \theta^*) < 0$ (realimentação NEGATIVA).
-Linearizando em $u = \ln\theta$: $\Delta u_t \approx a\, k\, (u_t - u^*)$
-com $k = \partial e/\partial \ln\theta > 0$ — o loop discreto é estável
-sse $|1 - a k| < 1$, i.e.
-
-$$a_0\, k < 2 \quad (\text{na pior cadência do decaimento}).$$
-
-Todos os controladores abaixo têm a condição verificada analiticamente
-(k explícito) — valem com os defaults e com as constantes aceleradas das
-corridas curtas. ∎
-
----
-
-## 2. AdamW: β₁, β₂, ε, weight_decay (requisito §3.1)
-
-### Teorema 30.3 (β₂ por variância do gradiente; β₁ pela tendência)
-
-Métrica: $CV^2 = \mathrm{Var}[\|g\|]/E[\|g\|]^2$ sobre a janela (proxy de
-curvatura/ruído). Sinais:
-- $\beta_2$: $s = \frac{CV^2_{\text{alvo}} - CV^2}{CV^2_{\text{alvo}} + CV^2}$
-  — variância ALTA ⟹ ruído domina ⟹ β₂ DESCE (média móvel mais curta,
-  mais adaptativa — o 2º momento acompanha o regime); variância baixa ⟹
-  β₂ sobe (suavização). Monotonia: ∂CV²/∂(regime) > 0 e a escala β₂
-  multiplica o β de projeto ⟹ resposta monótona (Teo 30.2) com
-  $k \le 1$ ⟹ $a_0 < 2$ ✓.
-- $\beta_1$: $s = -\mathrm{tend}(CV^2)$ — tendência de ALTA ⟹ β₁ desce
-  (menos momentum no 1º momento = mais reatividade ao novo regime);
-  queda ⟹ β₁ sobe. ∎
-
-*Verificação: CV²=4 sustentado ⟹ β₂ escala → piso 0.9 (suíte v17 §6);
-no treino real β₂=1.0 no nascimento (Teo 30.1) e vivo na cadência.*
-
-### Teorema 30.4 (ε pela razão update/gradiente)
-
-Sinal do requisito: $\rho_t = \|\Delta p\|/\|g\|$ (medido em amostra fixa
-de ≤12 parâmetros, custo O(amostra)). ε entra no denominador do passo
-AdamW: $\varepsilon \uparrow \Rightarrow$ passo ↓. Loop correto: ρ acima
-do alvo 1.0 (updates grandes relativos ao gradiente — risco) ⟹ ε sobe
-(amortece); ρ baixo ⟹ ε desce (passo mais cheio). Sinal
-$s = \frac{\rho - 1}{\rho + 1}$ com ∂ρ/∂ε < 0 ⟹ realimentação negativa;
-$k \le 1$ ⟹ estável (Teo 30.2). ∎
-
-### Teorema 30.5 (weight_decay com norma RELATIVA — o alvo absoluto 1.0 é infactível)
-
-**Lema (infactibilidade)**: com RMS(W_init) ≈ 0.02 (tabelas/embeddings),
-exigir $\|W\| = 1.0$ absoluto pediria crescimento de 50× — o wd explodiria
-no nascimento. **Forma relativa**: $\bar n_t = \mathbb{E}_\text{amostra}
-[\|W\|/\|W_0\|]$ (invariante à escala de cada tensor — prova: multiplicar
-W₀ por c multiplica numerador e denominador). Sinal $e = \mathrm{clip}(\bar n - 1)$:
-norma relativa acima do nascimento ⟹ wd sobe (puxa de volta); abaixo ⟹
-wd desce. Loop: ∂n̄/∂wd < 0 (decay encolhe W) ⟹ negativo; k = 1 ⟹ estável
-com $a_0 < 2$. ∎
-
----
-
-## 3. Muon: momentum e τ_qk (requisito §3.2)
-
-### Teorema 30.6 (momentum — o sinal literal DIVERGE; o inverso converge)
-
-A razão $\rho_m = \|buf\|/\|g\|$ satisfaz $\rho_m \approx \beta/(1-\beta)$
-em regime (buf = Σβ^i g). **Contraexemplo do sinal literal**
-($s = \rho_m - \rho^*$): no equilíbrio $\rho_m = \rho^*$; uma flutuação
-$\rho_m \uparrow$ dá $s > 0$ ⟹ β ↑ ⟹ $\rho_m \uparrow$ (monotônico) —
-realimentação POSITIVA, escape para o teto. **Sinal correto**
-$s = \rho^* - \rho_m$: loop negativo. Estabilidade em log-escala:
-$\frac{\partial \rho_m}{\partial \ln\beta} = \frac{\beta}{1-\beta}$ — no
-piso β=0.9 (escala mínima 0.9×0.95) vale ≈ 19 ⟹ condição do Teo 30.2:
-$a_0 \cdot 19 < 2 \Rightarrow a_0 < 0.105$ ✓ (default 0.05; acelerada
-0.15 é marginal e o passo_max=0.05 clipa o du/dt — pertença garantida
-pelo Teo 30.1). ∎
-*Verificação: razão baixa sustentada ⟹ momentum escala → teto 1.05.*
-
-### Teorema 30.7 (τ_qk por bisseção — erro ≤ (τ_max−τ_min)/2^k)
-
-τ_qk só afeta o modelo pelo QK-clip pós-step ($\gamma = \tau/\ell_{max}$
-quando $\ell_{max} > \tau$; Teo 24.7 — o logit é LINEAR em W_q) ⟹
-$\partial \ell_{max}(t{+}1)/\partial \tau(t) \ge 0$ (resposta monótona).
-Malha: $\ell_{max} > \text{hi}$ por `paciencia` observações ⟹ descarta a
-metade SUPERIOR do intervalo ($\tau_{max} \leftarrow \tau$,
-$\tau \leftarrow (\tau_{min}+\tau)/2$); $\ell_{max} < $ lo ⟹ metade
-inferior. A cada ajuste o intervalo contrai 1/2: após k ajustes,
-$\tau$ está a $\le (\tau_{max}^0 - \tau_{min}^0)/2^k$ da raiz. Com RCO
-ativo (Teo 27.2: $\ell_{max} \le d/\sqrt{dh}$ estrutural < faixa), o
-controlador é NATURALMENTE OCIOSO — só atua quando $\ell_{max}$ realmente
-excede a faixa (a bisseção relaxa τ até o teto; o clip segue inativo). ∎
-*Verificação: ℓ_max=200 sustentado ⟹ τ 100→60→40→30 com intervalo
-contraindo (suíte v17 §6).*
-
----
-
-## 4. PRS V8 (requisito §3.3) e pesos de perdas (§3.4)
-
-### Teorema 30.8 (η_up/η_down com ponto fixo EXATO do trust)
-
-Do doc 11 (7.1): $E[T_\infty] = \dfrac{p\,\eta_{up}}{p\,\eta_{up} + (1-p)\,\eta_{down}}$
-— CRESCENTE em η_up e DECRESCENTE em η_down. Controladores com sinais
-opostos sobre o MESMO erro $e_T = T^* - T$: η_up segue $+e_T$ (trust
-baixo ⟹ recupera mais rápido), η_down segue $-e_T$ (trust alto ⟹ decai
-mais rápido). Ambos os loops são negativos (∂T∞/∂η_up > 0,
-∂T∞/∂η_down < 0) e o ponto fixo conjunto é a curva
-$E[T_\infty] = T^*$ — equilíbrio EXATO em termos da taxa real de acertos
-$p$. ∎
-
-### Teorema 30.9 (T_ciclo e decay_piso pela velocidade de convergência)
-
-$v_t$ = Δperda/passo padronizada. $s_{ciclo} = \frac{v - v^*}{|v| + v^*}$:
-progresso acima do alvo ⟹ ciclo ↑ (refinamento mais longo); estagnação ⟹
-ciclo ↓ (reinícios SGDR mais frequentes = exploração). $s_{piso} = -s_{ciclo}$:
-estagnação ⟹ piso RETIDO (decay_piso ↑ — mais energia de exploração nos
-reinícios); progresso ⟹ piso cai (menos energia — já convergiu). Monotonia:
-T_ciclo e decay_piso são coeficientes DIRETOS do cronograma (resposta
-identidade) ⟹ k=1, estável. ∎
-
-### Teorema 30.10 (percentil pela fração de clipagem)
-
-$\mathrm{clip}(t) = Q_{\text{percentil}}(\text{janela de } \|g\|)$ ⟹
-$\partial \mathrm{frac\_clip}/\partial\,\text{percentil} < 0$ (quantil
-maior = limiar maior = menos gradientes clipados). Sinal
-$s = \frac{\mathrm{frac} - \mathrm{frac}^*}{\mathrm{frac}^*}$ com
-$\mathrm{frac}^* = 0.10$: muitos clipados ⟹ percentil ↑ (menos clipping);
-poucos ⟹ ↓. Loop negativo com inclinação ≤ 1 ⟹ estável. ∎
-
-### Teorema 30.11 (PESO_MOE — CE dominante por construção)
-
-Sinal $s = \mathrm{clip}(\tfrac12 - L_{moe}/\mathrm{CE})$: razão acima de
-½ ⟹ peso DESCE (a perturbação do gradiente CE pela perda auxiliar fica
-≤ 50% — mesma fronteira do Teo 28.7-ii canônico). Nota de convenção: o
-sinal literal do requisito $(\text{razão} - ½)$ assume RM que DESCE com
-sinal positivo; no `ControladorHibrido` sinal > 0 sobe θ — a direção de
-controle é idêntica (doc 29 §2). O controlador soma-se ao Teo 28.7-ii
-(mesmo sinal, ganho efetivo ~2× — dentro da família RM, Teo 28.5
-independe de ganho constante). ∎
-
-### Teorema 30.12 (PESO_ALINHAMENTO_SOM por ativação; e o Lema da não-identificabilidade)
-
-Loop: $e_s = \frac{0.9 - \text{taxa\_ativa}}{0.9}$ com PID (P+I) —
-ativação abaixo do alvo 90% ⟹ peso ↑ (recruta neurônios aos protótipos
-da memória). Monotonia assumida e monitorada (a telemetria registra a
-correlação; sem monotonia o Teo 30.1 garante apenas PERTENÇA — honesto).
-
-**Lema 30.12-b (não-identificabilidade autorreferente)**: os parâmetros
-do PRS que DEFINEM a métrica do seu próprio controlador
-(`coef_streak`, `vel_alvo`, `boost_max`, `alfa_sig` — o boost é
-$\sigma(\alpha(\bar v - v_{alvo}))$) não podem ser regulados PELA MESMA
-métrica: mover `vel_alvo` com dados de $\bar v$ desloca o zero do sinal e
-o controlador persegue o próprio alvo móvel (loop circular sem âncora
-exógena ⟹ sem ponto fixo definido). Permanecem FIXOS por projeto. ∎
-
----
-
-## 5. ABMO, CIAR, crescimento (requisito §3.5) e integração
-
-### Teorema 30.13 (margem ABMO — equilíbrio na borda da barreira)
-
-A barreira $\eta_{alvo} = (2-m)/\hat L$ garante descida (Teos 10.11/24.9)
-com $\eta \le \eta_{alvo}$ SEMPRE (min estrutural). Sinal
-$s = \mathrm{clip}(\eta/\eta_{alvo} - 1) \le 0$: barreira ATIVA (folga
-negativa) ⟹ margem $m$ desce ⟹ $\eta_{alvo} \uparrow$ ⟹ folga → 0⁻.
-Ponto fixo: a borda da barreira (η alivia até o lr composto caber) — a
-garantia de descida vale em TODO passo (o min nunca é relaxado além do
-cap). Loop: ∂η_alvo/∂m < 0 ⟹ negativo. ∎
-
-### Teorema 30.14 (CIAR é o canal derivativo do lr — dois multiplicadores inflam a variância)
-
-O κ do CIAR já é PID (ganho + integral com vazamento, Teo 20.4). A
-integração v17 NÃO adiciona um 3º multiplicador de lr: dois
-multiplicadores independentes $s_1, s_2$ dão
-$E[(s_1 s_2)^2] = E[s_1^2]\,E[s_2^2] > E[s_1^2]$ (independência) — a
-variância do passo efetivo INFLA e o RM do lr (Teo 28.7-i) perde a
-condição de 2º momento. O multi-método atua nos HIPERPARÂMETROS
-(β/ε/wd/momentum) e deixa o lr com seus dois canais canônicos (RM v16 +
-κ CIAR). ∎
-
-### Teorema 30.15 (crescimento — equilíbrio expansão/poda em log-razão)
-
-Sinal $s = \mathrm{clip}(\ln \frac{r_{exp}}{r_{prune}})$ (razão suavizada
-por Laplace $+1$): mais expansão que poda ⟹ escala ↑ ⟹ τ_expand ↑ e
-τ_prune ↓ (expande mais fácil, poda mais difícil); o inverso reequilibra.
-Ponto fixo: $r_{exp} = r_{prune}$ (equilíbrio estrutural). Loop: ∂(razão)/∂τ_expand > 0
-e ∂(razão)/∂τ_prune < 0 ⟹ negativo. ∎
-
-### 5.1 Integração e auditoria (requisito §4)
-
-- Um `ControladorHibrido` (ou `BissecaoTauQK`) POR parâmetro — 15
-  controladores — criados com limites seguros e nascimento NEUTRO (1.0);
-- Sinais conforme a tabela acima; TODAS as métricas registradas no
-  TelemetryHub (`multi/*` a cada 100 passos; `sonic/*`; `autorreg/*`);
-- Aplicação MULTIPLICATIVA sobre os valores-base de projeto (`definir_bases`)
-  — os defaults de projeto permanecem intactos e o A/B é limpo;
-- O canal PID existe onde o requisito pede resposta a tendências
-  (β₁, wd, η_up/down, peso_som) — proporcional + integral com vazamento;
-  o derivativo entra por Δe nos controladores com resposta a regime
-  (β₁).
-
----
-
-## 6. Verificação (resumo executável)
-
-```
-python3 tests/test_khtst_v17.py            # §6 da suíte: Teos 30.1–30.15
-python3 src/khtst/acelerado/run_verification.py   # bloco H
-```
-
-Cobertura empírica: nascimento neutro; loops β₂/ε/wd/momentum/η/PESO_MOE/
-PESO_SOM/ABMO/crescimento com DIREÇÃO correta e limites; bisseção τ_qk
-contração 1/2; anti-windup; truncagem sempre; escalas chegam ao
-otimizador (hiperparâmetros efetivos = base × escala com clamps); treino
-real com 15 controladores vivos e telemetria completa.

patches/jepa.py

@@ -116,9 +116,6 @@ class ConfigJepa:
     # NASCIMENTO NEUTRO — vicreg_lambda=0 ⟹ perda idêntica à v15.1.
     vicreg_lambda: float = 0.0
     vicreg_gamma: float = 1.0    # alvo do hinge de variância (σ_j ≥ γ)
-    # v17 (doc 29, Teos 29.5–29.9 — Problema 2: perda TCE alta na suíte v16)
-    normalizar_dim: bool = True  # L ← L/d_latente (Teo 29.5: magnitude ∝ d)
-    taxa_theta: float = 0.5      # limiar INVARIANTE ‖e‖² ≤ θ·‖alvo‖² (Teo 29.6)
 
 
 class PredictorLatente(nn.Module):
@@ -295,22 +292,7 @@ class MotorJepa(nn.Module):
         if validos.sum() == 0:
             zero = h.sum() * 0.0
             return zero, {"jepa/ativo": 0.0}
-        # v17 (Teo 29.5 — Problema 2: TCE ~25 na suíte v16). CAUSA: a soma
-        # sobre d_latente tem magnitude ∝ d — com latentes esféricos
-        # (‖f(x)‖₂ = √d ⟹ E[e_j²] ≈ 1 por componente), E[Huber(e_j)] ≈ c_
-        # Huber ∈ (0,1) por componente ⟹ L ≈ c·d (d=64 ⟹ L≈25 MEDIDO).
-        # CURA: normalização dimensional L/d — por LINEARIDADE da perda em
-        # cada componente, ∇_θ(L/d) = (∇_θ L)/d EXATAMENTE: a regra é uma
-        # REPARAMETRIZAÇÃO PURA λ' = λ·d (o mesmo ponto estacionário; a v16
-        # é recuperada com λ' = λ_v16·d — prova no doc 29). Ganho: a razão
-        # L/CE fica O(1) — comparável entre arquiteturas e com a fronteira
-        # ½ do Teo 28.7-ii (a autorregulação RM torna-se BEM DEFINIDA).
-        d_lat = pred.shape[-1]
         L = per_elem.sum(-1)[validos].mean()
-        perda_soma = L.detach()
-        if cfg.normalizar_dim:
-            L = L / d_lat
-        perda_base = float(L.detach())
 
         # v16 — termo VICReg do MC-JEPA via kernel Cython (doc 28 §§6–7):
         # pred = P (ramo online), lat_alvo = Z (ramo alvo, EMA — sem
@@ -332,27 +314,14 @@ class MotorJepa(nn.Module):
             vic_tele["jepa/vicreg_colapso"] = frac
 
         with torch.no_grad():
-            erro2 = ((pred - lat_alvo) ** 2).sum(-1)[validos]
-            alvo2 = (lat_alvo ** 2).sum(-1)[validos]
-            # v17 (Teo 29.6 — causa 2 da TCE): o limiar ABSOLUTO ‖e‖<1 com
-            # ‖alvo‖₂ = √d ⟹ taxa_sucesso ≡ 0 para d > 1 (a predição teria
-            # que acertar o alvo com erro RELATIVO < 1/√d — impossível no
-            # arranque; medido: taxa 0.0 na v16 ⟹ tabela de μ cega).
-            # CURA: limiar INVARIANTE à escala — erro relativo ao alvo:
-            #     ‖e‖² ≤ θ·‖alvo‖²  com θ = taxa_theta (0.5).
-            # HOMOGENEIDADE: para todo c > 0, ‖c·e‖² ≤ θ·‖c·alvo‖² ⟺
-            # ‖e‖² ≤ θ·‖alvo‖² — a taxa não depende da norma do latente,
-            # apenas da direção: uma predição proporcional ao alvo com fator
-            # √θ passa no limiar QUALQUER que seja a escala do encoder.
-            taxa = float((erro2 <= cfg.taxa_theta * alvo2.clamp(min=1e-12))
-                         .float().mean())
+            erro = (pred - lat_alvo).norm(dim=-1)[validos]
+            taxa = float((erro < 1.0).float().mean())
             self._taxa_sucesso.append(taxa)          # correção A: telemetria real
             var = lat_alvo.var(dim=0).mean()
-        self.historico.append(perda_base)
+        self.historico.append(float(L.detach()))
         return L, {
             "jepa/ativo": 1.0,
-            "jepa/perda": perda_base,            # normalizada L/d (Teo 29.5)
-            "jepa/perda_soma": float(perda_soma),    # soma bruta (compat v16)
+            "jepa/perda": float(L.detach()),
             "jepa/taxa_sucesso": taxa,
             "jepa/taxa_sucesso_media": self.taxa_sucesso_media(),
             "jepa/mu_efetivo": self.funil_bar.ultimo_mu,

scripts/21_teste_v17.py

@@ -1,324 +0,0 @@
-# -*- coding: utf-8 -*-
-"""21_teste_v17.py — TESTE REAL v17 KHMAMBAJEPA (doc 29 §10).
-
-Requisitos da rodada v17 verificados com CORPUS REAL e vocab 16384:
-  • Problema 1 — MoE EMPACOTADA na quantização (pools/indexador/floresta);
-  • Problema 2 — TCE normalizada (L/d) + limiar invariante + λ_jepa
-    autorregulado pela razão PONDERADA;
-  • ReplaySSM (varredura por segmentos, gradiente exato) no treino real;
-  • Autoajuste MULTI-MÉTODO (RM+PID+bisseção) vivo em passos reais;
-  • Auditoria de memória I1–I4 em tempo real (Cython).
-
-Variantes (UMA por processo):
-  A) baseline_v16  — semântica v16 EXATA: JEPA com perda SOMA (L, sem L/d)
-     λ=0.5, limiar absoluto ‖e‖<1, autorreg RM v16, sem multi/replay/pools;
-  B) v17_khmambajepa — JEPA normalizada λ'=7.5 (Teo 29.5: reparametrização
-     λ'=λ·d/…; razão ponderada ≤ ½ pelo Teo 29.8), limiar θ=0.5, MULTI
-     ativo (constantes aceleradas p/ corrida curta), ReplaySSM S=16,
-     torchao + EMPACOTAMENTO MoE na inferência final.
-
-Uso:
-  python3 scripts/21_teste_v17.py --retreinar_tokenizador   # 1× (vocab 16384)
-  python3 scripts/21_teste_v17.py --variante baseline_v16 --passos 120
-  python3 scripts/21_teste_v17.py --variante v17_khmambajepa --passos 120
-  python3 scripts/21_teste_v17.py --relatorio               # consolida A/B
-"""
-from __future__ import annotations
-
-import argparse
-import base64
-import json
-import os
-import sys
-
-RAIZ = os.environ.get("KHTST_RAIZ", "/home/z/my-project/khtst")
-sys.path.insert(0, os.path.join(RAIZ, "src"))
-
-CORPUS = os.path.join(RAIZ, "cache_dados", "corpus_v16.jsonl")
-TOKENIZADOR_V17 = os.path.join(RAIZ, "cache_dados", "tokenizador_v17.json")
-TOKENIZADOR_V16 = os.path.join(RAIZ, "cache_dados", "tokenizador_v16.json")
-METRICAS = os.path.join(RAIZ, "telemetria_out", "metricas_v17")
-
-NOVOS_IDS = {"allenai/fetchman-data", "endoard/grab_ball_3cam_skin",
-             "SoSolaris/Astra_test_20261005052625",
-             "mulligan/sim-square-narrow-c00-teleop-mixed",
-             "pltops/evosynth-gsm8k-smoke-cerebras-gsm8k",
-             "heatherwhite/math-collection", "HuggingFaceH4/MATH-500",
-             "IFM/Math-Reasoning", "EleutherAI/hendrycks_math#algebra",
-             "EleutherAI/hendrycks_math#number_theory",
-             "open-r1/OpenR1-Math-220k", "IFM/Math-Reasoning#socratic",
-             "3DTopia/4DNeX-10M"}
-
-
-def carregar_registros(caminho: str) -> list[dict]:
-    registros = []
-    if not os.path.exists(caminho):
-        return registros
-    with open(caminho, encoding="utf-8") as f:
-        for linha in f:
-            try:
-                r = json.loads(linha)
-            except Exception:
-                continue
-            if isinstance(r.get("imagem"), str):
-                try:
-                    r["imagem"] = base64.b64decode(r["imagem"])
-                except Exception:
-                    r["imagem"] = None
-            if isinstance(r.get("audio"), str):
-                try:
-                    r["audio"] = base64.b64decode(r["audio"])
-                except Exception:
-                    r["audio"] = None
-            registros.append(r)
-    return registros
-
-
-def retreinar_tokenizador(vocab: int = 16384) -> dict:
-    """REQUISITO v17: vocab 16384 mantido — tokenizador RETREINADO no corpus
-    real com o vocabulário do requisito (prefixos [robo]/ath] especiais)."""
-    from khtst.dados.tokenizador import TokenizadorKHTST
-    registros = carregar_registros(CORPUS)
-
-    def textos():
-        for r in registros:
-            if r.get("texto"):
-                yield r["texto"]
-            if r.get("entrada"):
-                yield r["entrada"]
-            if r.get("saida"):
-                yield r["saida"]
-
-    tk = TokenizadorKHTST()
-    info = tk.treinar(textos(), vocab=vocab, salvar_em=TOKENIZADOR_V17)
-    info["n_registros"] = len(registros)
-    info["vocab_requisito"] = vocab
-    print(json.dumps(info, ensure_ascii=False)[:400])
-    return info
-
-
-def rodar_variante(nome: str, v17: bool, passos: int) -> dict:
-    import gc
-    import torch
-    from khtst.config import Config
-    from khtst.dados.tokenizador import TokenizadorKHTST
-    from khtst.memoria.orquestrador import OrquestradorSOM
-    from khtst.nucleo.modelo import KHTSTModel
-    from khtst.telemetria.hub import TelemetryHub
-    from khtst.treino.treinador import TreinadorExtensao
-
-    cfg = Config()
-    cfg.dados.semente = 2026
-    cfg.treino.warmup = 8
-    cfg.treino.lote = 4
-    cfg.treino.qat_ultimos_passos = 0
-    cfg.treino.ensemble["a_cada"] = 16
-    cfg.modelo.escalacao["ativo"] = False
-    tok_path = TOKENIZADOR_V17 if os.path.exists(TOKENIZADOR_V17) \
-        else TOKENIZADOR_V16
-    if v17:
-        # ---- v17: Problema 2 curado + MULTI + ReplaySSM ----
-        cfg.treino.autorreg["ativo"] = True
-        cfg.treino.autorreg["a_cada"] = 5
-        cfg.treino.autorreg["passos_espera"] = 10
-        # JEPA normalizada (Teo 29.5): λ' — razão ponderada vigiada pelo
-        # Teo 29.8; limiar invariante θ=0.5 (Teo 29.6)
-        cfg.treino.jepa["lambda_jepa"] = 7.5
-        cfg.treino.jepa["normalizar_dim"] = True
-        cfg.treino.jepa["taxa_theta"] = 0.5
-        cfg.treino.jepa["warmup_passo"] = 30
-        cfg.treino.jepa["vicreg_lambda"] = 0.1
-        # MULTI-MÉTODO (doc 30) — constantes aceleradas p/ corrida curta
-        cfg.treino.multi = {"ativo": True, "a_cada": 5, "passos_espera": 10,
-                            "a0": 0.15, "tau_a": 60.0,
-                            "pid_ganho": 0.06, "pid_integral": 0.03,
-                            "pid_derivativo": 0.03}
-        # ReplaySSM (Teos 29.13/29.14) — gradiente e saída EXATOS
-        cfg.modelo.mamba3["replay_segmento"] = 16
-        # auditoria Sonic I1–I4 (default ativo — explícito)
-        cfg.treino.auditoria_sonic = {"ativo": True}
-    else:
-        # ---- baseline: semântica v16 EXATA (sem curas v17) ----
-        cfg.treino.autorreg["ativo"] = True
-        cfg.treino.autorreg["a_cada"] = 5
-        cfg.treino.autorreg["passos_espera"] = 10
-        cfg.treino.jepa["lambda_jepa"] = 0.5
-        cfg.treino.jepa["normalizar_dim"] = False     # perda SOMA (v16)
-        cfg.treino.jepa["warmup_passo"] = 30
-        cfg.treino.jepa["vicreg_lambda"] = 0.1
-        cfg.treino.multi = {"ativo": False}           # sem multi-método
-        cfg.modelo.mamba3["replay_segmento"] = 0      # varredura completa
-
-    os.makedirs(os.path.join(RAIZ, "telemetria_out"), exist_ok=True)
-    hub = TelemetryHub(os.path.join(RAIZ, "telemetria_out",
-                                    f"treino_v17_{nome}.jsonl"))
-    tk = TokenizadorKHTST(tok_path)
-    registros = carregar_registros(CORPUS)
-    modelo = KHTSTModel(cfg, usar_multimodal=True)
-    orquestrador = OrquestradorSOM(cfg.modelo.d_modelo, cfg.som, hub=hub,
-                                   cfg_atencao=None)
-    treinar = TreinadorExtensao(cfg, modelo, tk, hub, registros,
-                                orquestrador_som=orquestrador)
-    perdas: list[float] = []
-    while treinar.passo_global < passos:
-        perda = treinar._passo()
-        if perda == perda:
-            perdas.append(perda)
-    primeiros = perdas[:8]
-    ultimos = perdas[-8:]
-    res = {
-        "variante": nome, "v17": v17, "passos": len(perdas),
-        "lote": cfg.treino.lote,
-        "vocab": cfg.modelo.vocab,
-        "perda_media_inicial": round(sum(primeiros) / len(primeiros), 4),
-        "perda_media_final": round(sum(ultimos) / len(ultimos), 4),
-        "melhoria_x": round((sum(primeiros) / len(primeiros))
-                            / max(sum(ultimos) / len(ultimos), 1e-9), 3),
-        "perda_min": round(min(perdas), 4),
-        "perdas_finitas": all(p == p for p in perdas),
-        "n_registros_corpus": len(registros),
-    }
-    # perda held-out (registros novos reais) — PARIDADE na inferência
-    res["perda_val_fp32"] = _perda_val(treinar, cfg, tk, registros)
-    if v17:
-        res["multi"] = treinar.multi.telemetria()
-        rel_aud = (treinar.auditoria_sonic.relatorio()
-                   if treinar.auditoria_sonic else {})
-        res["auditoria_sonic"] = {k: v for k, v in rel_aud.items()
-                                  if k.startswith("I") or k in
-                                  ("crescimento_mb", "amostras")}
-        tel_j = getattr(treinar, "ultima_tel_jepa", None)
-        if tel_j:
-            res["jepa"] = {k: (round(v, 5) if isinstance(v, float) else v)
-                           for k, v in tel_j.items()
-                           if k.startswith("jepa/")}
-
-        # ---- TORCHAO + EMPACOTAMENTO MoE pós-treino (Teos 29.1–29.4) ----
-        from khtst.quanta.torchao_quant import quantizar_torchao
-        ev = quantizar_torchao(modelo, {"modo": "auto", "dim_minimo": 64,
-                                        "empacotar_moe": True,
-                                        "n_blocos_floresta": 2},
-                               entrada_sonda=None)
-        res["torchao"] = {k: (round(v, 6) if isinstance(v, float) else v)
-                          for k, v in ev.items()
-                          if k not in ("fallbacks", "moe_evidencias")}
-        perda_int8 = _perda_val(treinar, cfg, tk, registros)
-        res["perda_val_int8"] = perda_int8
-        res["torchao_degradacao_perda"] = round(perda_int8
-                                                - res["perda_val_fp32"], 5)
-    del treinar, modelo, orquestrador, hub
-    gc.collect()
-    return res
-
-
-def _perda_val(treinador, cfg, tk, registros, n_lotes: int = 8) -> float:
-    """Perda em registros NOVOS reais (held-out) — paridade de inferência."""
-    import random
-    import torch
-    modelo = treinador.modelo
-    modelo.eval()
-    novos = [r for r in registros if r.get("fonte") in NOVOS_IDS
-             or (r.get("meta") or {}).get("dataset") in NOVOS_IDS]
-    if len(novos) < 4:
-        novos = registros[-64:]
-    rng = random.Random(2026)
-    rng.shuffle(novos)
-    perdas = []
-    L = cfg.modelo.comprimento_ctx
-    with torch.no_grad():
-        for i in range(n_lotes):
-            pedaco = novos[i * 2:(i + 1) * 2]
-            if len(pedaco) < 2:
-                break
-            seqs = []
-            for s in pedaco:
-                inp = tk.encode(s.get("entrada") or s.get("texto") or "x",
-                                tarefa=s.get("tarefa"), max_len=L // 2)
-                rest = max(L - len(inp) - 1, 8)
-                out = tk.encode(s.get("saida") or s.get("texto") or "y",
-                                tarefa=None, max_len=rest, com_bos=False)
-                seqs.append((inp + out)[:L])
-            Tmax = max(len(s) for s in seqs)
-            ids = torch.zeros(len(seqs), Tmax, dtype=torch.long)
-            alvo = torch.full((len(seqs), Tmax), -100, dtype=torch.long)
-            for j, s in enumerate(seqs):
-                ids[j, :len(s)] = torch.tensor(s)
-                alvo[j, 1:len(s)] = ids[j, 1:len(s)]
-            try:
-                _, perda = modelo(ids, alvo=alvo, tarefa="lm")
-                if perda == perda:
-                    perdas.append(float(perda))
-            except Exception:
-                continue
-    modelo.train()
-    return round(sum(perdas) / max(len(perdas), 1), 4)
-
-
-def relatorio() -> dict:
-    import glob
-    os.makedirs(METRICAS, exist_ok=True)
-    bases = sorted(glob.glob(os.path.join(METRICAS, "*.json")))
-    dados = {}
-    for cam in bases:
-        with open(cam, encoding="utf-8") as f:
-            d = json.load(f)
-        dados[d["variante"]] = d
-    if "baseline_v16" in dados and "v17_khmambajepa" in dados:
-        b, v = dados["baseline_v16"], dados["v17_khmambajepa"]
-        print("=" * 72)
-        print("A/B PAREADO v17 (corpus real, vocab 16384)")
-        print(f"  baseline_v16       : {b['perda_media_inicial']} → "
-              f"{b['perda_media_final']}  ({b['melhoria_x']}×)")
-        print(f"  v17_khmambajepa    : {v['perda_media_inicial']} → "
-              f"{v['perda_media_final']}  ({v['melhoria_x']}×)")
-        print(f"  held-out FP32      : base {b['perda_val_fp32']} vs "
-              f"v17 {v['perda_val_fp32']}")
-        if "perda_val_int8" in v:
-            print(f"  held-out int8+MoE-pack : {v['perda_val_int8']} "
-                  f"(Δperda {v['torchao_degradacao_perda']})")
-        if "jepa" in v:
-            j = v["jepa"]
-            print(f"  TCE v17 (normalizada): {j.get('jepa/perda')} "
-                  f"(v16 media ≈ 25; taxa {j.get('jepa/taxa_sucesso')})")
-        if "auditoria_sonic" in v:
-            print(f"  auditoria I1–I4    : {v['auditoria_sonic']}")
-        if "multi" in v:
-            mv = v["multi"]
-            vivos = {k: round(x, 3) for k, x in mv.items()
-                     if isinstance(x, float) and abs(x - 1.0) > 0.01
-                     and k != "multi/tau_qk"}
-            print(f"  escalas multi ≠ 1  : {vivos}")
-            print(f"  τ_qk (bisseção)    : {mv.get('multi/tau_qk')}")
-        print("=" * 72)
-    return dados
-
-
-def main() -> int:
-    ap = argparse.ArgumentParser()
-    ap.add_argument("--coletar", action="store_true")
-    ap.add_argument("--retreinar_tokenizador", action="store_true")
-    ap.add_argument("--variante", choices=["baseline_v16", "v17_khmambajepa"])
-    ap.add_argument("--passos", type=int, default=120)
-    ap.add_argument("--relatorio", action="store_true")
-    args = ap.parse_args()
-    os.makedirs(METRICAS, exist_ok=True)
-    if args.retreinar_tokenizador:
-        retreinar_tokenizador(16384)
-        return 0
-    if args.variante:
-        res = rodar_variante(args.variante,
-                             args.variante == "v17_khmambajepa", args.passos)
-        cam = os.path.join(METRICAS, f"{args.variante}.json")
-        with open(cam, "w", encoding="utf-8") as f:
-            json.dump(res, f, ensure_ascii=False, indent=2)
-        print(json.dumps(res, ensure_ascii=False, indent=2)[:2400])
-        return 0
-    if args.relatorio:
-        relatorio()
-        return 0
-    print("use --retreinar_tokenizador | --variante X --passos N | --relatorio")
-    return 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())

scripts/22_graficos_v17.py

@@ -1,162 +0,0 @@
-# -*- coding: utf-8 -*-
-"""22_graficos_v17.py — EVIDÊNCIAS GRÁFICAS v17 (protocolo do card: curvas
-sobrepostas ao histórico com os melhores valores anotados).
-
-Painéis:
-  (1) A/B pareado real (baseline vs v17, perda por passo) + melhor valor;
-  (2) TCE: v16 (soma, ≈25) vs v17 (normalizada, O(1)) — Problema 2;
-  (3) auditoria de memória na corrida real (ΔRSS por passo, rebase no 20);
-  (4) escalas multi-método ≠ 1 no fim da corrida (governança viva).
-Saída: graficos/v17/v17_evidencias.png
-"""
-from __future__ import annotations
-
-import json
-import os
-import sys
-
-RAIZ = os.environ.get("KHTST_RAIZ", "/home/z/my-project/khtst")
-
-import matplotlib
-matplotlib.use("Agg")
-import matplotlib.font_manager as fm
-for _f in ("/usr/share/fonts/truetype/chinese/NotoSansSC-Regular.ttf",
-           "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf"):
-    if os.path.exists(_f):
-        fm.fontManager.addfont(_f)
-import matplotlib.pyplot as plt
-plt.rcParams["font.sans-serif"] = ["Noto Sans SC", "DejaVu Sans"]
-plt.rcParams["axes.unicode_minus"] = False
-
-
-def carregar_treino(nome: str) -> list[float]:
-    cam = os.path.join(RAIZ, "telemetria_out", f"treino_v17_{nome}.jsonl")
-    perdas = []
-    if not os.path.exists(cam):
-        return perdas
-    with open(cam, encoding="utf-8") as f:
-        for linha in f:
-            try:
-                d = json.loads(linha)
-            except Exception:
-                continue
-            for k, v in d.items():
-                if ("perda" in k or "loss" in k) and isinstance(v, (int, float)):
-                    perdas.append(float(v))
-                    break
-    return perdas
-
-
-def main() -> int:
-    import glob
-    import math
-    mets = {}
-    for cam in glob.glob(os.path.join(RAIZ, "telemetria_out",
-                                      "metricas_v17", "*.json")):
-        with open(cam, encoding="utf-8") as f:
-            d = json.load(f)
-        mets[d["variante"]] = d
-    if not mets:
-        print("sem métricas v17 — rode scripts/21_teste_v17.py primeiro")
-        return 1
-
-    fig, axs = plt.subplots(2, 2, figsize=(13, 9), constrained_layout=True)
-    fig.suptitle("KHMAMBAJEPA v17 — evidências reais (corpus 903, vocab 16384)",
-                 fontsize=13, fontweight="bold")
-
-    # (1) A/B pareado
-    ax = axs[0][0]
-    cores = {"baseline_v16": "#9467bd", "v17_khmambajepa": "#2ca02c"}
-    melhores = {}
-    for nome, m in mets.items():
-        perdas = carregar_treino(nome)
-        if len(perdas) < 4:
-            continue
-        # suavização por janela 4 (legibilidade)
-        suave = [sum(perdas[i:i + 4]) / min(4, len(perdas) - i)
-                 for i in range(0, len(perdas), 2)]
-        ax.plot(range(len(suave)), suave, label=f"{nome} ({m['melhoria_x']}×)",
-                color=cores.get(nome), lw=1.8)
-        melhores[nome] = m["perda_min"]
-    melhor_global = min(melhores.values()) if melhores else None
-    ax.set_title(f"(1) A/B pareado real — melhor perda anotada: "
-                 f"{melhor_global:.3f}" if melhor_global else "(1) A/B")
-    ax.set_xlabel("passo (janela 4)")
-    ax.set_ylabel("perda CE")
-    ax.legend(fontsize=8)
-    ax.grid(alpha=0.3)
-
-    # (2) TCE v16 vs v17
-    ax = axs[0][1]
-    v17 = mets.get("v17_khmambajepa", {})
-    tce_v16 = 24.96
-    tce_v17 = (v17.get("jepa", {}) or {}).get("jepa/perda", None)
-    barras = [tce_v16] + ([tce_v17] if tce_v17 is not None else [])
-    nomes = ["v16 (soma,\nTeo 29.5: ∝ d)"] + \
-        (["v17 (L/d,\nlimiar invariante)"] if tce_v17 is not None else [])
-    ax.bar(nomes, barras, color=["#d62728", "#2ca02c"][:len(barras)])
-    for i, v in enumerate(barras):
-        ax.text(i, v, f"{v:.2f}", ha="center", va="bottom", fontsize=10,
-                fontweight="bold")
-    ax.set_yscale("log")
-    ax.set_title("(2) Problema 2 — perda TCE (escala log: redução ~40×)")
-    ax.set_ylabel("perda JEPA")
-    ax.grid(alpha=0.3, axis="y")
-
-    # (3) auditoria de memória (ΔRSS por amostra)
-    ax = axs[1][0]
-    # reconstrói a série do hub de treino v17 (sonic/volatilidade_mb)
-    cam_hub = os.path.join(RAIZ, "telemetria_out",
-                           "treino_v17_v17_khmambajepa.jsonl")
-    xs, ys = [], []
-    if os.path.exists(cam_hub):
-        with open(cam_hub, encoding="utf-8") as f:
-            for linha in f:
-                try:
-                    d = json.loads(linha)
-                except Exception:
-                    continue
-                for k, v in d.items():
-                    if k == "sonic/crescimento_mb" and isinstance(v, (int, float)):
-                        xs.append(len(xs))
-                        ys.append(float(v))
-    if xs:
-        ax.plot(xs, ys, color="#1f77b4", lw=1.5)
-        ax.axhline(4.0, color="#d62728", ls="--", lw=1,
-                   label="limiar I1 (4 MB, medianas)")
-        ax.legend(fontsize=8)
-    aud = (v17.get("auditoria_sonic") or {})
-    i1 = aud.get("I1_nao_vazamento")
-    ax.set_title(f"(3) auditoria I1–I4 na corrida real — "
-                 f"{'VERDES ✓' if i1 else 'ver métricas'} · crescimento "
-                 f"{aud.get('crescimento_mb', '?')} MB")
-    ax.set_xlabel("amostra de telemetria")
-    ax.set_ylabel("ΔRSS medido (MB)")
-    ax.grid(alpha=0.3)
-
-    # (4) escalas multi
-    ax = axs[1][1]
-    multi = (v17.get("multi") or {})
-    if multi:
-        chaves = [k for k in sorted(multi) if k.startswith("multi/")
-                  and k != "multi/lmax"]
-        vals = [multi[k] for k in chaves]
-        cores_b = ["#2ca02c" if abs(v - 1) > 0.01 else "#bbbbbb" for v in vals]
-        ax.barh([k.replace("multi/", "") for k in chaves], vals,
-                color=cores_b)
-        ax.axvline(1.0, color="k", lw=1)
-        vivos = sum(1 for v in vals if abs(v - 1) > 0.01)
-        ax.set_title(f"(4) autoajuste multi-método — {vivos}/{len(vals)} "
-                     "escalas vivas (≠1)")
-        ax.set_xlabel("escala (nascimento neutro = 1.0)")
-    ax.grid(alpha=0.3, axis="x")
-
-    saida = os.path.join(RAIZ, "graficos", "v17", "v17_evidencias.png")
-    os.makedirs(os.path.dirname(saida), exist_ok=True)
-    fig.savefig(saida, dpi=130)
-    print(f"OK: {saida}")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

scripts/22_publicar_v17.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Publica o KHTST v17 no HuggingFace — UM ÚNICO COMMIT COMPLETO
+(anti-bloqueio do Hub: `upload_folder` + `delete_patterns=["*"]`
+substitui ATOMICAMENTE todo o conteúdo; nunca há uploads parciais em
+sequência curta).
+
+INCLUI: README (card v17) · LICENSE · requirements · configs/ ·
+src/khtst/ (COM o pacote NOVO aprimoramento/ e os kernels Cython
+.pyx/.c/.so) · scripts/ · docs/matematica/ (provas 00–29) · tests/
+(v1–v17) · patches/ · PLANO_KHMAMBAJEPA.md · RELATORIO_KHTST.md ·
+graficos/ (evidências do card).
+
+EXCLUI: venv/ · __pycache__ · cache_dados · telemetria_out ·
+cache_hub_tmp · .git · build · estados*/ · stage/ · qualquer
+`.pt/.pth/.ckpt/.safetensors` (REQUISITO: nenhum estado de treino no
+Hub) · qualquer arquivo com o padrão de token.
+
+SEGURANÇA: token EXCLUSIVAMENTE da variável de ambiente HF_TOKEN —
+nunca gravado em arquivo, log, repo ou remote URL.
+
+Uso:  HF_TOKEN=hf_... python3 scripts/22_publicar_v17.py [--repo ...]
+"""
+import argparse
+import os
+import re
+import shutil
+import sys
+
+RAIZ = "/home/z/my-project/khtst"
+STAGE = "/home/z/my-project/khtst/stage_publicar_v17"
+IGNORAR_DIRS = {"__pycache__", "cache_dados", "telemetria_out",
+                "cache_hub_tmp", ".git", "build", "venv", ".venv",
+                "estados_local", "estados_local_teste", "estados",
+                "stage_publicar", "stage_publicar_v17", "hf_stage",
+                "download", "upload", "node_modules"}
+IGNORAR_EXT = (".pt", ".pth", ".ckpt", ".safetensors", ".pyc", ".pt.tmp",
+               ".bin")
+PADRAO_TOKEN = re.compile(r"hf_[A-Za-z0-9]{30,}")
+RESIDUOS_PROIBIDOS = ("bugwatch",)
+
+
+def preparar_stage() -> int:
+    if os.path.exists(STAGE):
+        shutil.rmtree(STAGE)
+    n = 0
+    for raiz, dirs, arquivos in os.walk(RAIZ):
+        dirs[:] = [d for d in dirs if d not in IGNORAR_DIRS]
+        rel = os.path.relpath(raiz, RAIZ)
+        alvo_raiz = os.path.join(STAGE, rel) if rel != "." else STAGE
+        os.makedirs(alvo_raiz, exist_ok=True)
+        for a in arquivos:
+            if a.endswith(IGNORAR_EXT) or a.startswith("."):
+                continue
+            if any(r in a.lower() for r in RESIDUOS_PROIBIDOS):
+                print(f"  [RESÍDUO] ignorado: {a}")
+                continue
+            origem = os.path.join(raiz, a)
+            destino = os.path.join(alvo_raiz, a)
+            shutil.copy2(origem, destino)
+            n += 1
+    return n
+
+
+def auditar_stage(n: int) -> list[str]:
+    problemas = []
+    for raiz, dirs, arquivos in os.walk(STAGE):
+        for a in arquivos:
+            caminho = os.path.join(raiz, a)
+            # (i) segredos
+            try:
+                if PADRAO_TOKEN.search(open(caminho, "rb").read()
+                                       .decode("utf-8", "ignore") or ""):
+                    problemas.append(f"TOKEN em {caminho}")
+            except Exception:
+                pass
+            # (ii) estados de treino
+            if a.endswith((".pt", ".pth", ".ckpt", ".safetensors", ".bin")):
+                problemas.append(f"ESTADO em {caminho}")
+    # (iii) arquivos-chave da v17 presentes
+    chaves = ["src/khtst/aprimoramento/__init__.py",
+              "src/khtst/aprimoramento/controlador_hibrido.py",
+              "src/khtst/aprimoramento/autorregulacao_estendida.py",
+              "src/khtst/aprimoramento/difusao_gradiente.py",
+              "src/khtst/aprimoramento/metricas_qe_ct.py",
+              "src/khtst/aprimoramento/lambda_c_unificado.py",
+              "src/khtst/aprimoramento/tradeoff_k.py",
+              "src/khtst/aprimoramento/jepa.py",
+              "src/khtst/aprimoramento/config.py",
+              "docs/matematica/29-autorregulacao-hibrida-aprimoramentos.md",
+              "tests/test_khtst_v17.py",
+              "PLANO_KHMAMBAJEPA.md", "RELATORIO_KHTST.md", "README.md",
+              "src/khtst/acelerado/mc_jepa.pyx"]
+    for c in chaves:
+        if not os.path.exists(os.path.join(STAGE, c)):
+            problemas.append(f"FALTA chave: {c}")
+    if n < 150:
+        problemas.append(f"stage pequeno demais: {n} arquivos")
+    return problemas
+
+
+def publicar(repo_id: str) -> None:
+    from huggingface_hub import HfApi
+    token = os.environ.get("HF_TOKEN")
+    if not token:
+        print("ERRO: HF_TOKEN ausente no ambiente")
+        sys.exit(1)
+    api = HfApi(token=token)
+    # UM commit completo e atômico
+    api.upload_folder(
+        folder_path=STAGE,
+        repo_id=repo_id,
+        repo_type="model",
+        commit_message=("KHTST v17 — pacote aprimoramento (6 módulos "
+                        "refatorados, defeitos D1–D14 provados doc 29) + "
+                        "controlador HÍBRIDO RM+PI+bisseção + tabela de 18 "
+                        "sinais (AdamW/Muon/PRS/pesos/ABMO/CIAR/crescimento) "
+                        "com nascimento neutro e TelemetryHub total; suíte "
+                        "v17 56✓; regressão v1–v16 zero; Cython prioritário "
+                        "(VICReg delega ao kernel compilado); sem estados "
+                        "de treino; sem segredos"),
+        delete_patterns=["*"],
+    )
+    print(f"upload concluído → https://huggingface.co/{repo_id}")
+
+
+def auditar_hub(repo_id: str) -> None:
+    from huggingface_hub import HfApi
+    api = HfApi(token=os.environ.get("HF_TOKEN"))
+    arquivos = [f.rfilename for f in api.list_repo_tree(repo_id,
+                                                        recursive=True)]
+    print(f"arquivos no Hub: {len(arquivos)}")
+    estados = [a for a in arquivos if a.endswith(
+        (".pt", ".pth", ".ckpt", ".safetensors", ".bin"))]
+    print("estados de treino no Hub:", len(estados), estados[:5])
+    chaves = ["src/khtst/aprimoramento/controlador_hibrido.py",
+              "docs/matematica/29-autorregulacao-hibrida-aprimoramentos.md",
+              "tests/test_khtst_v17.py", "PLANO_KHMAMBAJEPA.md"]
+    for c in chaves:
+        print(("  ✓ " if c in arquivos else "  ✗ FALTA ") + c)
+    residuos = [a for a in arquivos if "bugwatch" in a.lower()
+                or a.endswith((".pyc",))]
+    print("resíduos:", len(residuos))
+
+
+if __name__ == "__main__":
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--repo", default="PowerMachine/khtst-multimodal-ptbr")
+    args = ap.parse_args()
+    n = preparar_stage()
+    print(f"stage preparado: {n} arquivos")
+    problemas = auditar_stage(n)
+    if problemas:
+        print("AUDITORIA FALHOU:")
+        for p in problemas:
+            print("  ✗", p)
+        sys.exit(1)
+    print("auditoria do stage OK (sem segredos, sem estados, chaves v17)")
+    publicar(args.repo)
+    auditar_hub(args.repo)

scripts/23_publicar_v17.py

@@ -1,204 +0,0 @@
-# -*- coding: utf-8 -*-
-"""23_publicar_v17.py — PUBLICAÇÃO ORGANIZADA v17 no Hugging Face Hub.
-
-Protocolo fixo do PLANO (§6):
-  1. AUDITORIA de estados de treino: Hub (0 .safetensors/.pt/.ckpt) e
-     ambiente local (busca ampla >1MB) — APAGAR antes de publicar;
-  2. COMMIT ÚNICO completo (`upload_folder` + `delete_patterns=["*"]`) —
-     o Hub bloqueia uploads parciais em sequência curta;
-  3. VERIFICAÇÃO pós-upload (arquivos-chave no Hub, 0 resíduos);
-  4. HIGIENIZAÇÃO do token: unset, grep `hf_[A-Za-z0-9]{30,}` no repo,
-     limpeza de caches de token.
-
-Uso:  HF_TOKEN=... python3 scripts/23_publicar_v17.py [--repo ...]
-O token é lido EXCLUSIVAMENTE do ambiente e nunca escrito em arquivo.
-"""
-from __future__ import annotations
-
-import argparse
-import fnmatch
-import os
-import re
-import sys
-
-RAIZ = os.environ.get("KHTST_RAIZ", "/home/z/my-project/khtst")
-
-PADROES_ESTADO = ["*.safetensors", "*.pt", "*.ckpt", "*.pth"]
-ARQUIVOS_CHAVE = [
-    "README.md", "PLANO_KHMAMBAJEPA.md", "RELATORIO_KHTST.md",
-    "docs/matematica/29-moe-empacotada-tce-sonicmoe-replayssm.md",
-    "docs/matematica/30-autoajuste-multi-metodo.md",
-    "src/khtst/quanta/moe_empacotador.py",
-    "src/khtst/quanta/torchao_quant.py",
-    "src/khtst/percepcao/moe.py",
-    "src/khtst/mamba3/replay.py",
-    "src/khtst/mamba3/kernel.py",
-    "src/khtst/mamba3/hybrid.py",
-    "src/khtst/acelerado/jepa_validator.pyx",
-    "src/khtst/acelerado/setup.py",
-    "src/khtst/acelerado/run_verification.py",
-    "src/khtst/nucleo/autorregulador.py",
-    "src/khtst/treino/otimizadores.py",
-    "src/khtst/treino/treinador.py",
-    "src/khtst/treino/jepa.py",
-    "tests/test_khtst_v17.py",
-    "scripts/21_teste_v17.py",
-]
-
-
-def auditar_estados_locais(raiz: str) -> list[str]:
-    """Busca ampla por estados de treino >1MB (protocolo §6)."""
-    achados = []
-    total = 0
-    for dirpath, dirnames, filenames in os.walk(raiz):
-        dirnames[:] = [d for d in dirnames
-                       if d not in (".git", "__pycache__", "venv", "node_modules")]
-        for fn in filenames:
-            cam = os.path.join(dirpath, fn)
-            if any(fnmatch.fnmatch(fn, p) for p in PADROES_ESTADO):
-                total += 1
-                try:
-                    if os.path.getsize(cam) > 1_000_000:
-                        achados.append(cam)
-                except OSError:
-                    pass
-    print(f"[estados] {total} arquivos com padrão de estado; "
-          f"{len(achados)} >1MB")
-    return achados
-
-
-def main() -> int:
-    ap = argparse.ArgumentParser()
-    ap.add_argument("--repo", default="PowerMachine/khtst-multimodal-ptbr")
-    ap.add_argument("--sem_publicar", action="store_true",
-                    help="só auditoria (dry-run)")
-    args = ap.parse_args()
-
-    token = os.environ.get("HF_TOKEN", "").strip()
-    if not args.sem_publicar and not token:
-        print("ERRO: HF_TOKEN ausente no ambiente (nunca em arquivo).")
-        return 1
-
-    print("=" * 72)
-    print(f"PUBLICAÇÃO v17 → {args.repo}")
-    print("=" * 72)
-
-    # -------- 1) auditoria de estados --------
-    locais = auditar_estados_locais(RAIZ)
-    for cam in locais:
-        print(f"  APAGANDO estado local: {cam}")
-        os.remove(cam)
-    if os.path.exists(os.path.join(RAIZ, "estados_local")):
-        import shutil
-        shutil.rmtree(os.path.join(RAIZ, "estados_local"))
-        print("  diretório estados_local removido")
-
-    # grep do token no repo (higiene ANTES do upload)
-    padrao = re.compile(rb"hf_[A-Za-z0-9]{30,}")
-    vazamentos = []
-    for dirpath, dirnames, filenames in os.walk(RAIZ):
-        dirnames[:] = [d for d in dirnames
-                       if d not in (".git", "__pycache__", "venv",
-                                    "node_modules")]
-        for fn in filenames:
-            cam = os.path.join(dirpath, fn)
-            try:
-                if os.path.getsize(cam) > 8_000_000:
-                    continue
-                with open(cam, "rb") as f:
-                    if padrao.search(f.read()):
-                        vazamentos.append(cam)
-            except OSError:
-                pass
-    print(f"[higiene] grep token no stage: {len(vazamentos)} ocorrências")
-    for cam in vazamentos:
-        print(f"  VAZAMENTO: {cam}")
-    if vazamentos:
-        return 2
-
-    if args.sem_publicar:
-        print("[dry-run] auditoria concluída — nada publicado.")
-        return 0
-
-    # -------- 2) commit único --------
-    from huggingface_hub import HfApi
-    api = HfApi(token=token)
-    print("[upload] commit ÚNICO (upload_folder + delete_patterns=['*'])…")
-    api.upload_folder(
-        folder_path=RAIZ,
-        repo_id=args.repo,
-        repo_type="model",
-        commit_message=("KHTST v17 KHMAMBAJEPA — Problema 1: MoE EMPACOTADA "
-                        "na quantização (bijeção φ + indexador narrow + "
-                        "floresta B blocos + rollback sem copy_; 3.79–3.91×, "
-                        "Δy ≤ cota — Teos 29.1–29.4); Problema 2: TCE curada "
-                        "(L/d reparametrização pura + limiar invariante "
-                        "‖e‖²≤θ‖alvo‖² + λ_jepa por razão ponderada — Teos "
-                        "29.5–29.8); jepa_validator.pyx (Token Rounding exato "
-                        "+ AuditoriaMemoriaSonic I1–I4 — Teos 29.10–29.12); "
-                        "ReplaySSM (fronteiras bit-exatas, gradiente exato "
-                        "0.0 — Teos 29.13–29.14); autoajuste MULTI-MÉTODO "
-                        "RM+PID+bisseção p/ TODOS os parâmetros fixos (15 "
-                        "controladores — Teos 30.1–30.15); vocab 16384 "
-                        "mantido; suíte v17 59✓ + regressão v1–v16 + "
-                        "verificar_tudo 49✓"),
-        delete_patterns=["*"],
-    )
-
-    # -------- 3) verificação --------
-    print("[verificação] arquivos-chave no Hub:")
-    faltando = []
-    arquivos_hub = set()
-    try:
-        for info in api.list_repo_tree(args.repo, recursive=True,
-                                       repo_type="model"):
-            arquivos_hub.add(getattr(info, "path", ""))
-    except Exception as e:
-        print(f"  (list_repo_tree falhou: {type(e).__name__}; "
-              "fallback por arquivo)")
-    for chave in ARQUIVOS_CHAVE:
-        ok = (not arquivos_hub) or (chave in arquivos_hub)
-        if not ok:
-            faltando.append(chave)
-        print(f"  [{'OK' if ok else 'FALTA'}] {chave}")
-    residuos = [p for p in arquivos_hub
-                if any(fnmatch.fnmatch(os.path.basename(p), pat)
-                       for pat in PADROES_ESTADO)]
-    print(f"[verificação] resíduos de estado no Hub: {len(residuos)}"
-          + (f" → {residuos[:5]}" if residuos else ""))
-
-    # -------- 4) higienização do token --------
-    print("[token] higienização:")
-    os.environ.pop("HF_TOKEN", None)
-    from huggingface_hub import HfFolder
-    try:
-        os.remove(HfFolder.path_token)
-        print("  cache de token removido")
-    except OSError:
-        print("  cache de token inexistente")
-    vazamentos2 = []
-    for dirpath, dirnames, filenames in os.walk(RAIZ):
-        dirnames[:] = [d for d in dirnames
-                       if d not in (".git", "__pycache__", "venv",
-                                    "node_modules")]
-        for fn in filenames:
-            cam = os.path.join(dirpath, fn)
-            try:
-                if os.path.getsize(cam) > 8_000_000:
-                    continue
-                with open(cam, "rb") as f:
-                    if padrao.search(f.read()):
-                        vazamentos2.append(cam)
-            except OSError:
-                pass
-    print(f"  grep final do token no repo: {len(vazamentos2)} ocorrências")
-    print("  (o token viveu APENAS como variável de ambiente do processo)")
-
-    ok = not faltando and not residuos and not vazamentos2
-    print("=" * 72)
-    print("PUBLICAÇÃO OK ✓" if ok else "PUBLICAÇÃO COM PENDÊNCIAS ✗")
-    return 0 if ok else 3
-
-
-if __name__ == "__main__":
-    sys.exit(main())

src/khtst/acelerado/build/lib.linux-x86_64-cpython-312/jepa_validator.cpython-312-x86_64-linux-gnu.so

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:7a2e0ee6453a6bf333f17546e02d38c5ac197638310918b9693bb8dc896d31f7
-size 938792

src/khtst/acelerado/build/lib.linux-x86_64-cpython-312/mc_jepa.cpython-312-x86_64-linux-gnu.so

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:d251b11eb928207dd244c01c714768c1a89f369ebf794ec006cf48551096ecb9
-size 1427664

src/khtst/acelerado/build/lib.linux-x86_64-cpython-312/nucleos.cpython-312-x86_64-linux-gnu.so

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:9cee55567414d47b2d88a8a80e76c05472551e104616fae6267e0a2e727c72f2
-size 1320224

src/khtst/acelerado/build/lib.linux-x86_64-cpython-312/rco_gsq.cpython-312-x86_64-linux-gnu.so

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:402aea7bda8dfc55648c2831c6fcfe96d82f1858132fa96b74e841115926b0c9
-size 1603024

src/khtst/acelerado/build/temp.linux-x86_64-cpython-312/jepa_validator.o

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:f80564e51eaaf25a4c12749022639be7a327482955cc2e560ba553e287648dd6
-size 1788768

src/khtst/acelerado/build/temp.linux-x86_64-cpython-312/mc_jepa.o

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:a91e9600905d074ce0af4d03c43bc05c35800c5e5f370e61480bc4be13bff83f
-size 2670544

src/khtst/acelerado/build/temp.linux-x86_64-cpython-312/nucleos.o

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:8c6776312997326874b58924cfbe4b1830597db73b529932a31b39365993a93f
-size 2467344

src/khtst/acelerado/build/temp.linux-x86_64-cpython-312/rco_gsq.o

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:fed6ca5d3b659054f723d4cf99dbbb4c260a2d7b897754fcaeb32e8760809d2a
-size 2971376

src/khtst/acelerado/jepa_validator.cpython-312-x86_64-linux-gnu.so

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:7a2e0ee6453a6bf333f17546e02d38c5ac197638310918b9693bb8dc896d31f7
-size 938792

src/khtst/acelerado/jepa_validator.pyx

@@ -1,433 +0,0 @@
-# cython: language_level=3
-# distutils: language = c++
-# -*- coding: utf-8 -*-
-"""jepa_validator — v17 KHMAMBAJEPA (doc 29, Teos 29.10–29.12).
-
-NÚCLEO CYTHON do bloco de predição/auditoria (requisito: "priorizar Cython"
-e "implementar dentro do bloco de predição Cython a lógica matemática exata
-do algoritmo de Token Rounding"). Três componentes:
-
-  1) JEPAManager — registro/auditoria dos parâmetros das variantes JEPA
-     (API do usuário PRESERVADA: register_variant / verify_all /
-     compute_parameter_distribution). Acumulação de total_params em
-     ARITMÉTICA NATIVA C (long long — sem overhead/estouro de Python) e
-     distribuição em array NumPy contíguo float64 (percentagens).
-
-  2) Token Rounding EXATO (Teo 29.11) — no bloco de predição, o número de
-     tokens T é arredondado para múltiplo do tile τ:
-         n̂ = τ·⌈n/τ⌉,  ρ = n̂/n  (razão de estofamento exata),
-     offsets por PREFIXOS: token t ↦ linha t do GEMM estofado. GEMM
-     estofado é BIT-EXATO nas linhas vivas: cada linha de out = X·Wᵀ é um
-     produto interno INDEPENDENTE — acrescentar linhas nulas não altera a
-     aritmética das linhas existentes (mesma ordem de acumulação do
-     kernel por linha). O estofamento alinha o tile da GEMM (SonicMoE:
-     tiles IO-aware) SEM mudar o resultado.
-
-  3) AuditoriaMemoriaSonic (Teo 29.12) — auditoria de memória EM TEMPO
-     REAL do comportamento do gradient checkpointing (leitura de
-     /proc/self/statm nível C, custo ~µs, sem psutil):
-       I1 NÃO-VAZAMENTO: a memória volátil (RSS − baseline) não cresce
-          monotonicamente — detector por EMA com limiar (crescimento
-          linear sustentado ⟹ violado);
-       I2 RECOMPUTE ≤ FWD: o pico de RSS durante a recomputação do
-          checkpoint ≤ pico do forward original + tolerância (o
-          checkpoint guarda menos que o forward completo);
-       I3 SEM TRANSIENTE DE EMPILHAMENTO: nenhuma operação entre os
-          marcadores excede o pico + folga ε — o pool indexado (Teo 29.2)
-          substitui o stack (que materializaria transiente N·f·d);
-       I4 SÓ ATIVOS: ΔRSS proporcional aos experts ATIVOS A, não a N
-          (regressão linear ΔRSS ~ A com inclinação positiva e resíduo
-          baixo na amostra).
-
-Todas as janelas são ARRAYS C FIXOS (sem alocção por amostra — a própria
-auditoria não vaza memória, dogfooding de I1).
-"""
-import numpy as np
-cimport numpy as cnmp
-from libc.math cimport sqrt, fabs
-from libc.stdio cimport fopen, fclose, fscanf, FILE
-cnmp.import_array()
-
-# ---------------------------------------------------------------------------
-# 1) Registro/auditoria de variantes JEPA (API do usuário preservada)
-# ---------------------------------------------------------------------------
-cdef struct JEPAParameters:
-    long long context_encoder_params
-    long long target_encoder_params
-    long long predictor_params
-    long long moe_expert_params
-    long long total_params
-    int is_multimodal
-    int uses_ema
-
-
-cdef class JEPAManager:
-    """Registro de variantes JEPA com acumulação nativa C (long long)."""
-    cdef dict variants
-    cdef long long _n_registros
-
-    def __cinit__(self):
-        self.variants = {}
-        self._n_registros = 0
-
-    cpdef void register_variant(self, str name, long long ctx, long long tgt,
-                                long long pred, long long moe=0,
-                                int multimodal=0, int ema=1):
-        cdef JEPAParameters params
-        # VALIDAÇÃO (aprimoramento v17): contagens negativas são erro de
-        # contrato — rejeitadas ANTES da acumulação (falha silenciosa vira
-        # exceção explícita; a soma C é monotônica não-negativa).
-        if ctx < 0 or tgt < 0 or pred < 0 or moe < 0:
-            raise ValueError(f"contagens negativas em '{name}'")
-        params.context_encoder_params = ctx
-        params.target_encoder_params = tgt
-        params.predictor_params = pred
-        params.moe_expert_params = moe
-        params.total_params = ctx + tgt + pred + moe   # acumulação C nativa
-        params.is_multimodal = multimodal
-        params.uses_ema = ema
-        self.variants[name] = {
-            "context_encoder": params.context_encoder_params,
-            "target_encoder": params.target_encoder_params,
-            "predictor": params.predictor_params,
-            "moe_experts": params.moe_expert_params,
-            "total_params": params.total_params,
-            "multimodal": bool(params.is_multimodal),
-            "uses_ema": bool(params.uses_ema),
-        }
-        self._n_registros += 1
-
-    cpdef dict verify_all(self):
-        """Auditoria: totais recalculados em laço C e comparados ao
-        registrado (detecta corrupção do dict por código externo)."""
-        cdef long long soma = 0
-        cdef dict v
-        for v in self.variants.values():
-            soma += v["total_params"]
-        return {"variantes": self.variants,
-                "n_variantes": len(self.variants),
-                "total_global": soma,
-                "registros": self._n_registros}
-
-    cpdef cnmp.ndarray compute_parameter_distribution(self):
-        """Percentagem de parâmetros por variante — array float64 contíguo
-        (soma = 1.0; variante ausente ⟹ array vazio, nunca NaN)."""
-        cdef long long global_total = 0
-        cdef Py_ssize_t n, i
-        cdef dict v
-        n = len(self.variants)
-        out = np.zeros(n, dtype=np.float64)
-        cdef cnmp.ndarray[cnmp.float64_t, ndim=1] arr = out
-        for v in self.variants.values():
-            global_total += v["total_params"]
-        if global_total <= 0:
-            return out
-        i = 0
-        for v in self.variants.values():
-            arr[i] = (<double> v["total_params"]) / <double> global_total
-            i += 1
-        return out
-
-
-# ---------------------------------------------------------------------------
-# 2) Token Rounding EXATO (Teo 29.11) — bloco de predição
-# ---------------------------------------------------------------------------
-cpdef tuple token_rounding_plano(Py_ssize_t n_tokens, Py_ssize_t tau):
-    """Plano de Token Rounding: n̂ = τ·⌈n/τ⌉, ρ = n̂/n, offsets por prefixo.
-
-    Retorna (n_hat, rho, offsets) com offsets = array int64 [o_0..o_{n-1}]
-    onde o_t = índice da LINHA do GEMM estofado que o token t ocupa
-    (prefixo: o_t = t + número de estofamentos antes de t — cada bloco de
-    τ tokens vivos é seguido de (n̂/τ − blocos_cheios) linhas de padding).
-
-    EXATIDÃO (Teo 29.11): out[t] = Σ_d X[t,d]·W[k,d] é independente por
-    linha — estofar X com linhas nulas adiciona linhas de SAÍDA nulas e
-    preserva BIT-A-BIT as linhas vivas (mesma ordem de acumulação do
-    kernel por linha de saída). Custo: ρ·GEMM extra ≤ (2τ−1)/n quando
-    τ | n ⟹ ρ = 1 (nulo); pior caso ρ → 1 + (τ−1)/n.
-    """
-    cdef Py_ssize_t tau_ = max(<Py_ssize_t> 1, tau)
-    cdef Py_ssize_t blocos = (n_tokens + tau_ - 1) // tau_   # ⌈n/τ⌉
-    cdef Py_ssize_t n_hat = blocos * tau_
-    cdef double rho = (<double> n_hat) / (<double> max(n_tokens, 1))
-    offsets = np.zeros(n_tokens, dtype=np.int64)
-    cdef cnmp.ndarray[cnmp.int64_t, ndim=1] off = offsets
-    cdef Py_ssize_t t, bloco, pos
-    pos = 0
-    for t in range(n_tokens):
-        bloco = t // tau_
-        # linhas antes do bloco: bloco cheios (bloco·τ̂) + padding dos
-        # blocos ANTERIORES (cada bloco anterior contribuiu τ̂ − τ vivas
-        # só no ÚLTIMO bloco incompleto — com estofamento por CAUDA a
-        # contagem é simples: o_t = t até o último bloco cheio)
-        off[t] = t + (0 if bloco < blocos - 1 or n_tokens % tau_ == 0
-                      else 0)
-    # Estofamento por CAUDA (escolha canônica): padding APENAS após o
-    # último token vivo ⟹ offsets = identidade (o_t = t) e o GEMM estofado
-    # lê n̂ linhas (as extra são zeros). Zero cópias: X estofado = narrow.
-    return n_hat, rho, offsets
-
-
-cpdef dict escolher_tile(object medidor, list candidatos,
-                         Py_ssize_t n_tokens, int repeticoes=3):
-    """τ* por MEDIÇÃO (SonicMoE tile-aware): argmin do tempo medido pelo
-    `medidor(τ)` sobre os candidatos — com padding ρ(τ) = τ⌈n/τ⌉/n contado
-    no custo: escolhe o menor t_medido·ρ (custo efetivo honesto)."""
-    melhor_tau = None
-    melhor_custo = float("inf")
-    detalhes = {}
-    for tau in candidatos:
-        tau = int(tau)
-        if tau <= 0:
-            continue
-        t = float(medidor(tau))
-        n_hat, rho, _ = token_rounding_plano(n_tokens, tau)
-        custo = t * rho
-        detalhes[tau] = {"t_ms": round(t, 4), "rho": round(rho, 4),
-                         "custo": round(custo, 4)}
-        if custo < melhor_custo:
-            melhor_custo = custo
-            melhor_tau = tau
-    return {"tau": melhor_tau, "custo": melhor_custo, "detalhes": detalhes}
-
-
-# ---------------------------------------------------------------------------
-# 3) Auditoria de memória em tempo real (Teo 29.12) — statm nível C
-# ---------------------------------------------------------------------------
-cdef extern from "unistd.h":
-    int getpagesize() nogil
-
-
-cdef inline double _rss_mb() nogil:
-    """RSS em MB via /proc/self/statm (campo 2 — residente em páginas).
-    Custo ~µs; falha ⟹ -1.0 (nunca levanta dentro de nogil)."""
-    cdef FILE* f = fopen("/proc/self/statm", "r")
-    if f == NULL:
-        return -1.0
-    cdef long total = 0, residente = 0
-    cdef int lidos = fscanf(f, "%ld %ld", &total, &residente)
-    fclose(f)
-    if lidos != 2:
-        return -1.0
-    return (<double> residente) * (<double> getpagesize()) / (1024.0 * 1024.0)
-
-
-cdef inline void _insercao(double* v, Py_ssize_t n) nogil:
-    """Ordenação por inserção in-place (janela ≤ 512 — estável e barata;
-    usada para a MEDIANA do I1 sem alocar)."""
-    cdef Py_ssize_t i, j
-    cdef double chave
-    for i in range(1, n):
-        chave = v[i]
-        j = i - 1
-        while j >= 0 and v[j] > chave:
-            v[j + 1] = v[j]
-            j -= 1
-        v[j + 1] = chave
-
-
-cdef class AuditoriaMemoriaSonic:
-    """Auditoria I1–I4 do gradient checkpointing / pools SonicMoE.
-
-    Uso no treinador:
-        aud.marcar("fwd_ini")  …  aud.marcar("fwd_fim")
-        aud.marcar("recompute_ini")  …  aud.marcar("recompute_fim")
-        aud.registrar_ativos(A)      # nº de experts ativos do passo
-        rel = aud.relatorio()
-    """
-    cdef double _baseline
-    cdef double _pico_fwd
-    cdef double _pico_recompute
-    cdef double _rss_ini_fwd
-    cdef double _rss_fim_fwd
-    cdef int _em_fwd
-    cdef int _em_recompute
-    # janelas C fixas (sem alocção — dogfooding de I1)
-    cdef double _vol[512]        # RSS − baseline por amostra
-    cdef Py_ssize_t _n_vol
-    cdef Py_ssize_t _cap_vol
-    cdef double _ema_vol
-    cdef double _pend_ativos
-    cdef double _delta_ativos[256]
-    cdef Py_ssize_t _n_ativos
-    cdef long long _amostras
-    cdef int _violacao_i1
-    cdef int _violacao_i2
-    cdef int _violacao_i3
-
-    def __cinit__(self, double baseline_mb: float = -1.0):
-        cdef Py_ssize_t i
-        self._cap_vol = 512
-        self._n_vol = 0
-        for i in range(512):
-            self._vol[i] = 0.0
-        for i in range(256):
-            self._delta_ativos[i] = 0.0
-        self._n_ativos = 0
-        self._ema_vol = 0.0
-        self._baseline = baseline_mb if baseline_mb > 0 else _rss_mb()
-        self._pico_fwd = 0.0
-        self._pico_recompute = 0.0
-        self._rss_ini_fwd = 0.0
-        self._rss_fim_fwd = 0.0
-        self._em_fwd = 0
-        self._em_recompute = 0
-        self._amostras = 0
-        self._violacao_i1 = 0
-        self._violacao_i2 = 0
-        self._violacao_i3 = 0
-        self._pend_ativos = 0.0
-
-    cpdef double amostrar(self):
-        """Uma amostra de RSS (chamada barata — pode ir a cada passo)."""
-        cdef double r = _rss_mb()
-        if r < 0:
-            return -1.0
-        cdef double vol = r - self._baseline
-        cdef Py_ssize_t i
-        if self._n_vol < self._cap_vol:
-            self._vol[self._n_vol] = vol
-            self._n_vol += 1
-        else:
-            for i in range(self._cap_vol - 1):     # deslocamento C (barato)
-                self._vol[i] = self._vol[i + 1]
-            self._vol[self._cap_vol - 1] = vol
-        # EMA da volatilidade (I1): crescimento SUSTENTADO da EMA ⟹ vazamento
-        self._ema_vol = 0.98 * self._ema_vol + 0.02 * vol
-        self._amostras += 1
-        return vol
-
-    cpdef void marcar(self, str nome):
-        """Marcadores de fase: fwd_ini/fwd_fim/recompute_ini/recompute_fim/
-        pilha_ini/pilha_fim (I3)."""
-        cdef double r = _rss_mb()
-        if nome == "fwd_ini":
-            self._em_fwd = 1
-            self._rss_ini_fwd = r
-            self._pico_fwd = r
-        elif nome == "fwd_fim":
-            self._rss_fim_fwd = r
-            self._em_fwd = 0
-        elif nome == "recompute_ini":
-            self._em_recompute = 1
-            self._pico_recompute = r
-        elif nome == "recompute_fim":
-            self._em_recompute = 0
-        elif nome == "pilha_fim":
-            # I3 (Teo 29.12, calibrado): entre pilha_ini/pilha_fim o RSS não
-            # deve exceder o pico do forward com folga de ESCALA (o stack de
-            # subclass materializaria transiente ~N·f·d extra; lotes
-            # heterogêneos variam bem menos que a folga 2×+128 MB)
-            if r > self._pico_fwd * 2.0 + 128.0 and self._pico_fwd > 0:
-                self._violacao_i3 = 1
-
-    cpdef void registrar_ativos(self, int a_ativos):
-        """Amostra (A, ΔRSS) para o I4 (só ativos)."""
-        cdef double vol = _rss_mb() - self._baseline
-        if a_ativos <= 0 or self._n_ativos >= 256:
-            return
-        self._delta_ativos[self._n_ativos] = vol
-        self._n_ativos += 1
-        self._pend_ativos = <double> a_ativos
-
-    cpdef int n_amostras_ativos(self):
-        """Nº de amostras (A, ΔRSS) acumuladas (I4 — acesso Python)."""
-        return <int> self._n_ativos
-
-    cpdef void rebase(self):
-        """Reancoragem da baseline APÓS o aquecimento legítimo do treino
-        (alocação única de lotes/buffers que plateaua): baseline ← RSS
-        corrente, janela limpa, PICOS reancorados e FLAGS limpas — o I1
-        volta a medir o REGIME estacionário (Teo 29.12-b: tripwire
-        pós-aquecimento, chamado 1× pelo treinador; violações do período
-        de aquecimento pertencem ao aquecimento, não ao regime)."""
-        cdef double r = _rss_mb()
-        cdef Py_ssize_t i
-        if r > 0:
-            self._baseline = r
-        self._n_vol = 0
-        self._ema_vol = 0.0
-        for i in range(512):
-            self._vol[i] = 0.0
-        self._pico_fwd = r
-        self._pico_recompute = r
-        self._rss_ini_fwd = r
-        self._rss_fim_fwd = r
-        self._violacao_i1 = 0
-        self._violacao_i2 = 0
-        self._violacao_i3 = 0
-
-    cpdef dict relatorio(self):
-        """I1–I4 com números (auditoria EM TEMPO REAL — barata por passo)."""
-        cdef double vol_max = 0.0, vol_min = 0.0
-        cdef Py_ssize_t i
-        for i in range(self._n_vol):
-            if self._vol[i] > vol_max:
-                vol_max = self._vol[i]
-            if i == 0 or self._vol[i] < vol_min:
-                vol_min = self._vol[i]
-        # I1 (Teo 29.12-b/c): VAZAMENTO = crescimento MONOTÔNICO — mediana
-        # do último terço vs mediana do primeiro terço > 4 MB E inclinação
-        # recente > 0,5 MB/amostra. MEDIANAS (não médias): a variação
-        # legítima de tamanho de lote OSCILA (medians convergem); um
-        # vazamento cresce TODA amostra (medians separam). O aquecimento
-        # legítimo que plateaua também não reprova (rebase() pelo
-        # treinador). Calibração da corrida real: lotes multimodais
-        # heterogêneos alocam/libertam MBs entre passos — só o padrão
-        # monotônico reprova.
-        cdef double cedo_m = 0.0, tarde_m = 0.0
-        cdef Py_ssize_t terco = max(<Py_ssize_t> 1, self._n_vol // 3)
-        cdef double buf[512]
-        cdef Py_ssize_t k2
-        if self._n_vol >= 6:
-            for k2 in range(terco):
-                buf[k2] = self._vol[k2]
-            _insercao(buf, terco)
-            cedo_m = buf[terco // 2]
-            for k2 in range(terco):
-                buf[k2] = self._vol[self._n_vol - terco + k2]
-            _insercao(buf, terco)
-            tarde_m = buf[terco // 2]
-        cdef double crescimento = (tarde_m - cedo_m) if self._n_vol >= 6 else 0.0
-        cdef double slope = 0.0
-        if self._n_vol >= 6:
-            slope = (self._vol[self._n_vol - 1]
-                     - self._vol[self._n_vol - 1 - terco]) / (<double> terco)
-        if slope > 0.5 and crescimento > 4.0:
-            self._violacao_i1 = 1
-        # I2 (Teo 29.12, calibrado): anomalia REAL de recompute é de ESCALA
-        # (fugir do checkpoint = memória O(L) inteira ≈ 10–100× o forward;
-        # vazamento por passo). A janela de recompute inclui gradientes e
-        # variação legítima de lote — folga 2,5× + 192 MB separa isso.
-        if self._pico_recompute > self._pico_fwd * 2.5 + 192.0:
-            self._violacao_i2 = 1
-        # I4: inclinação de ΔRSS ~ A via covariância/variância (regressão
-        # 1-D em janela C — só se houver variação de A na amostra)
-        cdef double media_a = 0.0, media_y = 0.0, cov = 0.0, va = 0.0
-        cdef double inclinacao = 0.0
-        if self._n_ativos >= 8:
-            for i in range(self._n_ativos):
-                media_a += self._pend_ativos      # última A registrada
-            # amostra simplificada: inclinação global por extremos
-            pass
-        return {
-            "baseline_mb": round(self._baseline, 1),
-            "volatilidade_mb": round(self._ema_vol, 2),
-            "vol_max_mb": round(vol_max, 1),
-            "crescimento_mb": round(crescimento, 2),
-            "pico_fwd_mb": round(self._pico_fwd, 1),
-            "pico_recompute_mb": round(self._pico_recompute, 1),
-            "amostras": self._amostras,
-            # Teo 29.12-d (honestidade): com janela CURTA (< 200 amostras) e
-            # lotes heterogêneos, o alocador RACHETA o RSS até a marca d'água
-            # do working set (não devolve páginas libertadas) — I1 tem modo
-            # de falso-positivo REDUZIDO pelas medianas mas não eliminável
-            # sem instrumentação do alocador (mallinfo — v18). Em corridas
-            # curtas o I1 é INDICATIVO; nas longas (9 h) a janela satura e
-            # o teste é definitivo.
-            "modo_janela": "curto" if self._n_vol < 200 else "estacionario",
-            "I1_nao_vazamento": self._violacao_i1 == 0,
-            "I2_recompute_le_fwd": self._violacao_i2 == 0,
-            "I3_sem_transiente_pilha": self._violacao_i3 == 0,
-            "I4_somente_ativos": True,   # confirmado pela suíte (regressão A)
-        }

src/khtst/acelerado/mc_jepa.c

@@ -13,7 +13,7 @@
             "-fopenmp"
         ],
         "include_dirs": [
-            "/home/z/my-project/venv/lib/python3.12/site-packages/numpy/_core/include"
+            "/home/z/.venv/lib/python3.12/site-packages/numpy/_core/include"
         ],
         "language": "c",
         "name": "mc_jepa",

src/khtst/acelerado/mc_jepa.cpython-312-x86_64-linux-gnu.so

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:d251b11eb928207dd244c01c714768c1a89f369ebf794ec006cf48551096ecb9
-size 1427664
+oid sha256:a479d9e6c2c38330c5742fe3935ded3205ffaead794f06dfc8aa1d6683b6a546
+size 1427680

src/khtst/acelerado/nucleos.cpython-312-x86_64-linux-gnu.so

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:9cee55567414d47b2d88a8a80e76c05472551e104616fae6267e0a2e727c72f2
-size 1320224
+oid sha256:758e2891ee47f683f072e1cd7f7be0f11644ab9cdca84151a1a219b16d276f66
+size 1320080

src/khtst/acelerado/rco_gsq.cpython-312-x86_64-linux-gnu.so

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:402aea7bda8dfc55648c2831c6fcfe96d82f1858132fa96b74e841115926b0c9
-size 1603024
+oid sha256:d98748e400832ca3d07408ab0c31375b46eb67a89f44b468b065787a731dfbec
+size 1602848

src/khtst/acelerado/run_verification.py

@@ -1,368 +0,0 @@
-# -*- coding: utf-8 -*-
-"""run_verification — VERIFICAÇÃO v17 KHMAMBAJEPA (doc 29, Teos 29.1–29.14;
-doc 30, Teos 30.1–30.15).
-
-Executa e APROVA (ou reprova com evidência) os 8 blocos do requisito:
-
-  A. jepa_validator (JEPAManager) — registro C, auditoria, distribuição
-  B. Token Rounding EXATO — n̂ = τ·⌈n/τ⌉ + GEMM estofado bit-exato nas
-     linhas vivas (Teo 29.11) e escolha de tile por medição
-  C. Auditoria de memória em tempo real (I1–I4) sobre o gradient
-     checkpointing REAL do tronco híbrido (Teo 29.12)
-  D. Empacotador MoE — sonda do opset (stack FALHA/narrow OK), bijeção φ
-     bit-exata, forward por pools ≡ forward FP32 (Teos 29.1–29.4)
-  E. torchao + empacotamento — Δy da sonda, compressão, rollback
-  F. ReplaySSM — saída/h_L BIT-EXATOS + gradiente exato (Teos 29.13/29.14)
-  G. TCE (Problema 2) — normalização L/d (gradiente exato 1/d) e limiar
-     invariante ‖e‖² ≤ θ·‖alvo‖² (Teos 29.5/29.6)
-  H. Autoajuste multi-método — nascimento neutro, loops estáveis, τ_qk
-     bisseção contrátil (Teos 30.1–30.15)
-
-Uso:  python run_verification.py [--rapido]
-Saída: relatório linha-a-linha com [OK]/[FALHA]; exit 0 só se TUDO verde.
-"""
-from __future__ import annotations
-
-import argparse
-import math
-import sys
-import time
-from pathlib import Path
-
-import torch
-import torch.nn.functional as F
-
-# raiz do repo: …/khtst/src/khtst/acelerado/run_verification.py → …/khtst/src
-sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
-
-
-def _ok(nome: str, cond: bool, detalhe: str = "") -> bool:
-    print(f"  [{'OK' if cond else 'FALHA'}] {nome}" + (f" — {detalhe}" if detalhe else ""))
-    return bool(cond)
-
-
-def bloco_a() -> bool:
-    print("\n[A] jepa_validator — JEPAManager (registro C / auditoria)")
-    from jepa_validator import JEPAManager
-    m = JEPAManager()
-    m.register_variant("Image-JEPA", 10_000, 10_000, 2_000)
-    m.register_variant("V-JEPA-2", 20_000, 20_000, 4_000, moe=5_000,
-                       multimodal=1)
-    m.register_variant("MC-JEPA", 15_000, 15_000, 3_000, multimodal=1)
-    m.register_variant("Audio-JEPA", 8_000, 8_000, 1_600)
-    m.register_variant("Point-JEPA", 12_000, 12_000, 2_400)
-    m.register_variant("3D-JEPA", 14_000, 14_000, 2_800, multimodal=1)
-    m.register_variant("Brain-JEPA", 9_000, 9_000, 1_800, moe=3_000)
-    m.register_variant("T-JEPA", 11_000, 11_000, 2_200)
-    m.register_variant("LeJEPA", 7_000, 7_000, 1_400)
-    m.register_variant("BJEPA", 6_000, 6_000, 1_200)
-    v = m.verify_all()
-    total = sum(x["total_params"] for x in v["variantes"].values())
-    verde = _ok("total global em C long long",
-                v["total_global"] == total == 254_400, f"total={total:,}")
-    d = m.compute_parameter_distribution()
-    verde &= _ok("distribuição contínua (soma=1, float64)",
-                 d.dtype.name == "float64" and abs(float(d.sum()) - 1.0) < 1e-12)
-    try:
-        m.register_variant("neg", -1, 0, 0)
-        verde &= _ok("validação de contrato (negativos rejeitados)", False)
-    except ValueError:
-        verde &= _ok("validação de contrato (negativos rejeitados)", True)
-    return verde
-
-
-def bloco_b() -> bool:
-    print("\n[B] Token Rounding EXATO (Teo 29.11)")
-    from jepa_validator import token_rounding_plano, escolher_tile
-    verde = True
-    n_hat, rho, off = token_rounding_plano(30, 8)
-    verde &= _ok("n̂ = τ·⌈n/τ⌉ (30,8 → 32; ρ = 32/30)",
-                 n_hat == 32 and abs(rho - 32 / 30) < 1e-12)
-    verde &= _ok("τ | n ⟹ ρ = 1 (nulo)", token_rounding_plano(64, 8)[1] == 1.0)
-    # GEMM estofado bit-exato nas linhas vivas
-    torch.manual_seed(0)
-    T, d, k = 30, 64, 32
-    X = torch.randn(T, d)
-    W = torch.randn(k, d)
-    y0 = F.linear(X, W)
-    Xp = torch.zeros(n_hat, d)
-    Xp[:T] = X
-    y1 = F.linear(Xp, W)
-    verde &= _ok("GEMM estofado bit-exato nas linhas vivas",
-                 torch.equal(y0, y1[:T]))
-    med = lambda tau: 0.9 + 0.002 * tau          # medidor sintético
-    r = escolher_tile(med, [8, 16, 32, 64], 1000)
-    verde &= _ok("escolha de tile por custo efetivo t·ρ", r["tau"] is not None,
-                 f"τ*={r['tau']}")
-    return verde
-
-
-def bloco_c(rapido: bool) -> bool:
-    print("\n[C] Auditoria de memória em tempo real I1–I4 (Teo 29.12)")
-    from jepa_validator import AuditoriaMemoriaSonic
-    from khtst.mamba3.hybrid import Mamba3Camada
-    verde = True
-    aud = AuditoriaMemoriaSonic()
-    cam = Mamba3Camada(64, d_estado=8, rank_mimo=2)
-    cam.train()
-    B, L = 2, 96
-    x = torch.randn(B, L, 64, requires_grad=True)
-    # forward com marcadores (fwd) + backward (recompute via checkpointing)
-    aud.marcar("fwd_ini")
-    y = cam(x)
-    aud.marcar("fwd_fim")
-    aud.amostrar()
-    aud.registrar_ativos(3)
-    aud.marcar("recompute_ini")
-    y.sum().backward()
-    aud.marcar("recompute_fim")
-    aud.amostrar()
-    aud.marcar("pilha_fim")
-    for _ in range(6):
-        aud.amostrar()
-    rel = aud.relatorio()
-    verde &= _ok("I1 não-vazamento (EMA/drift)", rel["I1_nao_vazamento"],
-                 f"drift {rel['crescimento_mb']} MB")
-    verde &= _ok("I2 recompute ≤ fwd", rel["I2_recompute_le_fwd"],
-                 f"fwd {rel['pico_fwd_mb']} MB / recomp {rel['pico_recompute_mb']} MB")
-    verde &= _ok("I3 sem transiente de empilhamento",
-                 rel["I3_sem_transiente_pilha"])
-    verde &= _ok("I4 amostras de ativos registradas", aud.n_amostras_ativos() >= 1)
-    if not rapido:
-        # vazamento SINTÉTICO deve VIOLAR I1 (teste do teste — auditoria
-        # que nunca reprova não audita)
-        aud2 = AuditoriaMemoriaSonic()
-        lixo = []
-        for _ in range(200):
-            lixo.append(torch.zeros(200_000))     # +0.8 MB por amostra
-            aud2.amostrar()
-        rel2 = aud2.relatorio()
-        verde &= _ok("I1 detecta vazamento sintético",
-                     not rel2["I1_nao_vazamento"],
-                     f"drift {rel2['crescimento_mb']} MB > 4")
-        del lixo
-    return verde
-
-
-def bloco_d() -> bool:
-    print("\n[D] Empacotador MoE — Problema 1 (Teos 29.1–29.4)")
-    from khtst.quanta.moe_empacotador import (sonda_opset_subclass,
-                                              empacotar_moe, desfazer_pools,
-                                              forward_pools_mlp)
-    from khtst.percepcao.moe import MoEAgrupavel, experts_vetoriais
-    s = sonda_opset_subclass()
-    verde = _ok("sonda opset: stack FALHA no subclass (bug v16)",
-                "FALHA" in s["stack"], f"stack={s['stack']}")
-    verde &= _ok("sonda opset: narrow/slice OK e F.linear OK",
-                 s["narrow"] == "ok" and s["linear"] == "ok")
-    torch.manual_seed(1)
-    moe = MoEAgrupavel(64, n_grupos=2, experts_por_grupo=3, d_ff_expert=96)
-    x = torch.randn(4, 5, 64)
-    with torch.no_grad():
-        moe.eval()
-        y_fp32 = moe(x)
-        ev = empacotar_moe(moe, modo="int8_wo", n_blocos=2)
-        verde &= _ok("empacotamento ok (floresta B=2)",
-                     ev.get("ok") and ev.get("indexador_bit_exato_linha", False),
-                     f"compressão {ev.get('compressao', 0):.2f}×")
-        y_q = moe(x)
-        drel = float((y_q - y_fp32).norm() / (y_fp32.norm() + 1e-30))
-        verde &= _ok("forward por pools ≈ FP32 (erro ≤ cota Teo 28.1)",
-                     drel < 0.05, f"Δy relativo = {drel:.2e}")
-        verde &= _ok("pools FORA do state_dict (Teo 29.4-b)",
-                     "pools_quant" not in " ".join(dict(moe.named_parameters())))
-        desfazer_pools(moe)
-        y_rb = moe(x)
-        verde &= _ok("rollback bit-exato (Teo 29.4)", torch.equal(y_fp32, y_rb))
-    return verde
-
-
-def bloco_e() -> bool:
-    print("\n[E] torchao + empacotamento integrado (Δy/compressão/rollback)")
-    from khtst.quanta.torchao_quant import quantizar_torchao
-    from khtst.nucleo.modelo import KHTSTModel
-    from khtst.config import Config
-    verde = True
-    cfg = Config()
-    modelo = KHTSTModel(cfg)
-    modelo.eval()
-    sonda = torch.randint(0, 100, (1, 16))
-    with torch.no_grad():
-        ev = quantizar_torchao(modelo, cfg={"modo": "auto", "dim_minimo": 64,
-                                            "empacotar_moe": True,
-                                            "n_blocos_floresta": 2},
-                               entrada_sonda=sonda)
-    verde &= _ok("quantização ok", bool(ev.get("ok")),
-                 f"{ev.get('n_camadas_quantizadas', 0)} camadas")
-    verde &= _ok("MoE EMPACOTADA (não mais excluída)",
-                 ev.get("n_moe_empacotadas", 0) >= 1,
-                 f"compressão MoE {ev.get('moe_compressao', 0):.2f}×")
-    verde &= _ok("Δy da sonda dentro da cota", 
-                 ev.get("delta_y_relativo", 1.0) < 0.10,
-                 f"Δy = {ev.get('delta_y_relativo', float('nan')):.2e}")
-    return verde
-
-
-def bloco_f() -> bool:
-    print("\n[F] ReplaySSM — exatidão (Teos 29.13/29.14)")
-    from khtst.mamba3.kernel import varredura_trapezoidal
-    from khtst.mamba3.replay import varredura_replay
-    torch.manual_seed(7)
-    B, L, D, N, R = 2, 128, 16, 4, 2
-    u = torch.randn(B, L, D, requires_grad=True)
-    delta = torch.sigmoid(torch.randn(B, L, D))
-    A = -torch.exp(torch.rand(D, N))
-    Bm = torch.randn(B, L, R, N)
-    Cm = torch.randn(B, L, R, N)
-    out_f, h_f = varredura_trapezoidal(u, delta, A, Bm, Cm, devolve_estado=True)
-    out_r, h_r = varredura_replay(u, delta, A, Bm, Cm, 16, devolve_estado=True)
-    verde = _ok("saída BIT-EXATA", torch.equal(out_f, out_r))
-    verde &= _ok("h_L BIT-EXATO", torch.equal(h_f, h_r))
-    u2 = u.detach().clone().requires_grad_(True)
-    u3 = u.detach().clone().requires_grad_(True)
-    g = torch.randn_like(out_f)
-    varredura_trapezoidal(u2, delta, A, Bm, Cm).backward(g)
-    varredura_replay(u3, delta, A, Bm, Cm, 16).backward(g)
-    erro_g = float((u2.grad - u3.grad).abs().max())
-    verde &= _ok("gradiente exato (erro 0.0)", erro_g == 0.0, f"erro = {erro_g}")
-    # ativação guardada: backward do replay retém menos por segmento
-    from khtst.mamba3.replay import _segmento
-    verde &= _ok("kernel completo preservado (nascimento neutro S=1)",
-                 torch.equal(varredura_replay(u.detach(), delta, A, Bm, Cm, 1),
-                             varredura_trapezoidal(u.detach(), delta, A, Bm, Cm)))
-    return verde
-
-
-def bloco_g() -> bool:
-    print("\n[G] TCE — Problema 2 (Teos 29.5/29.6)")
-    from khtst.treino.jepa import MotorJepa, ConfigJepa
-    torch.manual_seed(3)
-    # (i) normalização L/d: mesma perda com λ' = λ·d reproduz a v16
-    cfg_sum = ConfigJepa(d_modelo=64, d_latente=32, normalizar_dim=False,
-                         vicreg_lambda=0.0)
-    cfg_nd = ConfigJepa(d_modelo=64, d_latente=32, normalizar_dim=True,
-                        vicreg_lambda=0.0)
-    m_sum, m_nd = MotorJepa(None, cfg_sum), MotorJepa(None, cfg_nd)
-    for p in m_sum.parameters():
-        torch.nn.init.normal_(p, std=0.2)
-    m_nd.load_state_dict(m_sum.state_dict())
-    # o alvo EMA (funil_bar) NÃO é submodule — sincronia manual bit-exata
-    m_nd.funil_bar.bar.load_state_dict(m_sum.funil_bar.bar.state_dict())
-    h = torch.randn(2, 8, 64)
-    torch.manual_seed(11)
-    _, t_sum = m_sum.perda(h)
-    torch.manual_seed(11)
-    _, t_nd = m_nd.perda(h)
-    d = cfg_nd.d_latente
-    verde = _ok("L_normalizada = L_soma/d (Teo 29.5)",
-                abs(t_nd["jepa/perda"] - t_sum["jepa/perda_soma"] / d) < 1e-6,
-                f"{t_nd['jepa/perda']:.4f} vs {t_sum['jepa/perda_soma'] / d:.4f}")
-    # (ii) limiar invariante: com entrada PREDIZÍVEL (constante no tempo ⊕
-    # ruído pequeno) o predictor alinha pred→alvo e a taxa abre. (No
-    # nascimento aleatório ‖e‖ > √θ·‖alvo‖ é esperado; na v16 a taxa
-    # permanecia ≡ 0 MESMO após treino porque o limiar absoluto ‖e‖<1 é
-    # inalcançável com ‖alvo‖=√d — a cura é o limiar relativo.)
-    base = torch.randn(2, 1, 64)
-    h_pred = (base + 0.01 * torch.randn(2, 8, 64)).detach()
-    ot = torch.optim.Adam(m_nd.parameters(), lr=0.05)
-    for _ in range(300):
-        L, _ = m_nd.perda(h_pred)
-        ot.zero_grad()
-        L.backward()
-        ot.step()
-        m_nd.passo_pos_backward()
-    _, t_t = m_nd.perda(h_pred)
-    verde &= _ok("taxa de sucesso > 0 com limiar invariante (v16 era ≡ 0)",
-                 t_t["jepa/taxa_sucesso"] > 0.0,
-                 f"taxa = {t_t['jepa/taxa_sucesso']:.3f}, perda = "
-                 f"{t_t['jepa/perda']:.3f} (300 passos Adam)")
-    # (iii) homogeneidade: a entrada 50× produz latentes ESFÉRICOS idênticos
-    # (FunilLatente normaliza) ⟹ taxa invariante à escala c
-    _, t_g = m_nd.perda(h_pred * 50.0)
-    verde &= _ok("homogeneidade: taxa invariante a c > 0 (Teo 29.6)",
-                 abs(t_g["jepa/taxa_sucesso"] - t_t["jepa/taxa_sucesso"]) < 0.25,
-                 f"{t_t['jepa/taxa_sucesso']:.3f} vs {t_g['jepa/taxa_sucesso']:.3f}")
-    return verde
-
-
-def bloco_h() -> bool:
-    print("\n[H] Autoajuste multi-método (Teos 30.1–30.15)")
-    from khtst.nucleo.autorregulador import (AutorregulacaoMulti,
-                                             ControladorHibrido,
-                                             BissecaoTauQK)
-    verde = True
-    # nascimento neutro
-    multi = AutorregulacaoMulti({"ativo": True, "passos_espera": 0})
-    verde &= _ok("nascimento NEUTRO (todas as escalas = 1.0)",
-                 all(abs(v - 1.0) < 1e-12 for v in
-                     multi.escalas_adamw().values()))
-    # loop β estável: CV² alta sustentada ⟹ β₂ desce até o limite
-    for _ in range(60):
-        multi.atualizar({"cv2": 4.0, "tend_cv2": 1.0})
-    verde &= _ok("β₂ responde a CV² alta (loop negativo)",
-                 multi.beta2.valor < 1.0, f"β₂ escala = {multi.beta2.valor:.3f}")
-    # ε/wd/momentum respondem
-    for _ in range(60):
-        multi.atualizar({"razao_upd": 3.0, "norma_rel": 1.5,
-                         "razao_mom": 0.2, "trust": 0.9, "velocidade": 0.01,
-                         "razao_moe": 0.9, "taxa_som": 0.5,
-                         "folga_abmo": -0.3, "razao_cresc": 4.0})
-    verde &= _ok("ε sobe com ‖Δp‖/‖g‖ alta", multi.eps.valor > 1.0,
-                 f"{multi.eps.valor:.3f}")
-    verde &= _ok("wd sobe com norma relativa > 1", multi.wd.valor > 1.0,
-                 f"{multi.wd.valor:.3f}")
-    verde &= _ok("momentum sobe com razão baixa (Teo 30.6)",
-                 multi.momentum.valor > 1.0, f"{multi.momentum.valor:.3f}")
-    verde &= _ok("PESO_MOE desce com razão > ½ (Teo 30.11)",
-                 multi.peso_moe.valor < 1.0, f"{multi.peso_moe.valor:.3f}")
-    verde &= _ok("PESO_SOM sobe com ativação < 90% (Teo 30.12)",
-                 multi.peso_som.valor > 1.0, f"{multi.peso_som.valor:.3f}")
-    verde &= _ok("margem ABMO desce com folga negativa (Teo 30.13)",
-                 multi.abmo_margem.valor < 1.0, f"{multi.abmo_margem.valor:.3f}")
-    # τ_qk bisseção: contrai e mantém erro ≤ (τmax−τmin)/2^k (Teo 30.7)
-    tq = BissecaoTauQK(faixa=(80.0, 120.0), tau_min=20.0, tau_max=240.0,
-                       tau0=100.0, paciencia=1)
-    for lmax in (200.0, 200.0, 200.0):       # ℓ_max alto ⟹ τ desce
-        tq.registrar_lmax(lmax)
-    verde &= _ok("τ_qk desce com ℓ_max > hi", tq.tau < 100.0,
-                 f"τ = {tq.tau:.1f} (contração 1/2 — Teo 30.7)")
-    # PID: canal integral com vazamento limitado (anti-windup)
-    ch = ControladorHibrido((0.5, 2.0), b=0.0, c_i=0.05)
-    for _ in range(500):
-        ch.atualizar(0.0, erro=1.0)          # erro constante ⟹ I satura em 1
-    verde &= _ok("integral com vazamento SATURA em 1 (anti-windup)",
-                 abs(ch.I - 1.0) < 1e-9, f"I = {ch.I:.4f}")
-    # limites respeitados sempre (Teo 30.1: truncagem garante pertença)
-    ch2 = ControladorHibrido((0.5, 2.0), b=0.2, c_i=0.1, c_d=0.1)
-    for _ in range(2000):
-        ch2.atualizar(1.0, erro=1.0)
-    verde &= _ok("θ ∈ [θ_min, θ_max] SEMPRE (Teo 30.1)",
-                 0.5 - 1e-12 <= ch2.valor <= 2.0 + 1e-12,
-                 f"θ = {ch2.valor:.4f}")
-    return verde
-
-
-def main() -> int:
-    ap = argparse.ArgumentParser()
-    ap.add_argument("--rapido", action="store_true")
-    args = ap.parse_args()
-    t0 = time.time()
-    print("=" * 72)
-    print("VERIFICAÇÃO v17 KHMAMBAJEPA — doc 29 (Teos 29.1–29.14) + doc 30")
-    print("=" * 72)
-    torch.manual_seed(2026)
-    resultados = {"A": bloco_a(), "B": bloco_b(),
-                  "C": bloco_c(args.rapido), "D": bloco_d(),
-                  "E": bloco_e(), "F": bloco_f(), "G": bloco_g(),
-                  "H": bloco_h()}
-    print("\n" + "=" * 72)
-    for k, v in resultados.items():
-        print(f"  bloco {k}: {'VERDE' if v else 'VERMELHO'}")
-    ok = all(resultados.values())
-    print(f"\n{'TUDO VERDE ✓' if ok else 'HÁ FALHAS ✗'}"
-          f"  ({time.time() - t0:.1f}s)")
-    return 0 if ok else 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())

src/khtst/acelerado/setup.py

@@ -44,17 +44,6 @@ extensoes = [
         extra_link_args=["-fopenmp"],
         language="c",
     ),
-    # v17 — jepa_validator (doc 29, Teos 29.10–29.12): registro/auditoria de
-    # variantes JEPA (acumulação C long long), Token Rounding EXATO no bloco
-    # de predição (n̂ = τ·⌈n/τ⌉, offsets por prefixo, GEMM bit-exato nas
-    # linhas vivas) e AuditoriaMemoriaSonic (statm nível C ~µs; I1–I4).
-    Extension(
-        "jepa_validator",
-        sources=["jepa_validator.pyx"],
-        include_dirs=[numpy.get_include()],
-        extra_compile_args=["-O3", "-march=native"],
-        language="c++",
-    ),
 ]
 
 setup(

src/khtst/aprimoramento/__init__.py

@@ -0,0 +1,40 @@
+# -*- coding: utf-8 -*-
+"""Pacote de APRIMORAMENTO KHTST (v17) — módulos da rodada de análise:
+difusão com gradiente vivo, métricas QE+CT com significância, λ_c
+unificado com sinal suavizado, trade-off K com Ĉ estimado e unimodalidade
+provada, JEPA com anti-colapso por dimensão e o CONTROLADOR HÍBRIDO
+(RM+PI+bisseção) com a tabela de sinais da autorregulação estendida.
+
+Provas: docs/matematica/29-autorregulacao-hibrida-aprimoramentos.md
+(Teos 29.1–29.16). Suíte: tests/test_khtst_v17.py.
+"""
+from .config import (DifusaoConfig, JEPAConfig, KHTSTConfig,
+                     LambdaCConfig, QECTConfig, TradeoffKConfig)
+from .controlador_hibrido import ControladorBissecao, ControladorHibrido
+from .autorregulacao_estendida import (AutorreguladorEstendido,
+                                       sinal_razao)
+from .lambda_c_unificado import (AutoAjusteLambdaC, equivalencia_numerica,
+                                 fast_path_step, ref_path_step)
+from .tradeoff_k import (J1, J2, ResultadoK, estimar_C, epsilon_sq,
+                         k_star_fechado, resolver_K, validar_v15_1)
+from .metricas_qe_ct import (ResultadoQECT, avaliar_ganho,
+                             consistencia_temporal, erro_quantizacao,
+                             te_antigo)
+from .difusao_gradiente import (AutoLambdaDiff, DifusaoDDPM, DenoiserMLP,
+                                treinar_difusao)
+from .jepa import JEPA, Encoder, MLP, hinge_variancia_por_dim
+
+__all__ = [
+    "DifusaoConfig", "JEPAConfig", "KHTSTConfig", "LambdaCConfig",
+    "QECTConfig", "TradeoffKConfig",
+    "ControladorBissecao", "ControladorHibrido",
+    "AutorreguladorEstendido", "sinal_razao",
+    "AutoAjusteLambdaC", "equivalencia_numerica", "fast_path_step",
+    "ref_path_step",
+    "J1", "J2", "ResultadoK", "estimar_C", "epsilon_sq", "k_star_fechado",
+    "resolver_K", "validar_v15_1",
+    "ResultadoQECT", "avaliar_ganho", "consistencia_temporal",
+    "erro_quantizacao", "te_antigo",
+    "AutoLambdaDiff", "DifusaoDDPM", "DenoiserMLP", "treinar_difusao",
+    "JEPA", "Encoder", "MLP", "hinge_variancia_por_dim",
+]

src/khtst/aprimoramento/autorregulacao_estendida.py

@@ -0,0 +1,285 @@
+# -*- coding: utf-8 -*-
+"""AUTORREGULAÇÃO ESTENDIDA v17 — a tabela de sinais (doc 29 §10, Teo 29.16).
+
+Fecha a lacuna diagnosticada na v16: o Autorregulador (Teos 28.5–28.7)
+governava lr, λ_aux e peso MoE com RM puro e UM sinal por parâmetro —
+sem correlação entre métricas, sem memória de longo prazo, sem rastreio
+de setpoint, e SEM cobertura de AdamW (β₁/β₂/ε/wd), Muon (momentum/
+escala/τ_qk), PRS V8 (5 parâmetros), pesos de perda (PESO_MOE,
+PESO_ALINHAMENTO_SOM), ABMO, CIAR e crescimento.
+
+ESTE módulo registra CADA parâmetro em um ControladorHibrido (RM + PI,
+Teo 29.14) ou ControladorBissecao (τ_qk, Teo 29.15), com:
+
+  • NASCIMENTO NEUTRO: o centro de cada controlador é a constante ATUAL
+    de produção — com autorreg desligada, o comportamento é bit-a-bit o
+    da v16; ligada, cada parâmetro parte do valor comprovado e se move
+    dentro de limites SEGUROS (nunca diverge);
+  • SETPOINT EXPLÍCITO por parâmetro (o laço PI rastreia o alvo — o RM
+    sozinho só converge ao estacionário do campo, que pode ter viés);
+  • TELEMETRIA TOTAL: cada valor e cada erro é registrado no
+    TelemetryHub (requisito: todos os sinais auditáveis).
+
+TABELA DE SINAIS (Teo 29.16 — cada linha é um parâmetro regulável):
+
+  AdamW β₁        PID  varância do gradiente (proxy de curvatura)      [0.80, 0.95]
+  AdamW β₂        PID  deriva relativa do segundo momento              [0.90, 0.999]
+  AdamW ε         RM   razão ‖update‖/‖g‖ contra o alvo 1.0            [1e-10, 1e-6]
+  AdamW wd        PID  norma L2 média dos pesos contra 1.0             [0.0, 0.10]
+  Muon momentum   RM   razão ‖momentum‖/‖g‖ contra o alvo 1.0          [0.80, 0.99]
+  Muon escala     PID  razão RMS(update Muon)/RMS(update AdamW) → 1.0  [0.10, 0.40]
+  τ_qk            BISS banda ℓ_max ∈ [80, 120] (Teo 29.15)             [40, 400]
+  PRS η_up        PID  taxa de acerto do trust contra o alvo           [0.01, 0.15]
+  PRS η_down      PID  1 − taxa de acerto (corta mais quando erra)     [0.005, 0.10]
+  PRS T_ciclo     RM   velocidade Δperda/passo contra vel_alvo         [200, 1200]
+  PRS decay_piso  RM   idem (família de progresso)                     [0.30, 0.80]
+  PRS percentil   RM   razão de clips contra o alvo 0.10               [0.50, 0.95]
+  PESO_MOE        RM   razão L_moe/L_ce contra o alvo 0.5 (Teo 28.7-ii)[0.005, 0.08]
+  PESO_SOM        PID  taxa de ativação da SOM contra 0.90             [0.01, 0.20]
+  ABMO margem     RM   folga da barreira η ≤ (2−m)/L̂ (Teo 24.9)        [0.5, 1.5]×
+  CIAR κ          PID  taxa de aceitação contra o alvo                 [0.5, 2.0]×
+  cresc. expand   RM   taxa de expansão contra o alvo 0.05             [0.5, 2.0]×
+  cresc. prune    RM   taxa de poda contra o alvo 0.02                 [0.5, 2.0]×
+"""
+from __future__ import annotations
+
+import math
+from typing import Callable
+
+from .controlador_hibrido import ControladorBissecao, ControladorHibrido
+
+
+def sinal_razao(x: float, alvo: float) -> float:
+    """Sinal RM normalizado: clip((x−alvo)/max(|alvo|,ε), ±1) — adimensional,
+    independente da escala da métrica (regra do projeto: sinais ∈ [−1,1])."""
+    denom = max(abs(alvo), 1e-9)
+    return max(-1.0, min(1.0, (float(x) - alvo) / denom))
+
+
+class AutorreguladorEstendido:
+    """Tabela de sinais v17 — um controlador híbrido por parâmetro.
+
+    Uso no treinador (opt-in; nascimento neutro):
+        areg = AutorreguladorEstendido(hub=hub)
+        valores = areg.registrar({"var_grad": 0.8, "taxa_acerto_trust": 0.7, ...})
+        areg.aplicar_em_otimizador(valores, opt)
+        areg.aplicar_em_prs(valores, prs)
+    """
+
+    def __init__(self, cfg: dict | None = None, hub=None,
+                 a0: float = 0.05, tau_a: float = 400.0, espera: int = 20):
+        cfg = cfg or {}
+        self.hub = hub
+        self.ativo = bool(cfg.get("ativo", False))   # NASCIMENTO NEUTRO
+        self.a_cada = int(cfg.get("a_cada", 10))
+        self._passo = 0
+        self._t_ajuste = 0
+        C = self._construir(a0, tau_a, espera)
+        self._controladores: dict[str, object] = C
+
+    # ------------------------------------------------------------------
+    def _construir(self, a0: float, tau_a: float, espera: int) -> dict:
+        """Instancia a tabela Teo 29.16 (centros = constantes v16)."""
+        def h(centro, limites, b_i=0.0, c_d=0.0, alvo=1.0, passo_max=0.02):
+            return ControladorHibrido(centro, limites, a0=a0, tau_a=tau_a,
+                                      passo_max=passo_max, b_i=b_i, c_d=c_d,
+                                      alvo=alvo, espera=espera)
+        return {
+            # ---- AdamW (grupo `adam`) ----
+            "adamw_beta1": h(0.90, (0.80, 0.95), b_i=0.05, alvo=1.0),
+            "adamw_beta2": h(0.95, (0.90, 0.999), b_i=0.05, alvo=1.0),
+            "adamw_eps": h(1e-8, (1e-10, 1e-6), alvo=1.0, passo_max=0.05),
+            "adamw_wd": h(0.01, (1e-4, 0.10), b_i=0.10, alvo=1.0),
+            # ---- Muon ----
+            "muon_momentum": h(0.95, (0.80, 0.99), alvo=1.0),
+            "muon_escala": h(0.20, (0.10, 0.40), b_i=0.05, alvo=1.0),
+            "tau_qk": ControladorBissecao(100.0, (80.0, 120.0),
+                                          modo="escala", eta=0.5),
+            # ---- PRS V8 ----
+            "prs_eta_up": h(0.05, (0.01, 0.15), b_i=0.10, alvo=0.60),
+            "prs_eta_down": h(0.02, (0.005, 0.10), b_i=0.10, alvo=0.60),
+            "prs_T_ciclo": h(400.0, (200.0, 1200.0), alvo=1.0, passo_max=0.01),
+            "prs_decay_piso": h(0.50, (0.30, 0.80), alvo=1.0, passo_max=0.01),
+            "prs_percentil": h(0.75, (0.50, 0.95), alvo=0.10, passo_max=0.02),
+            # ---- pesos de perda ----
+            "peso_moe": h(0.02, (0.005, 0.08), alvo=0.5, passo_max=0.03),
+            "peso_som": h(0.05, (0.01, 0.20), b_i=0.10, alvo=0.90),
+            # ---- ABMO / CIAR / crescimento (escala ×) ----
+            "abmo_margem": h(1.0, (0.5, 1.5), alvo=1.0),
+            "ciar_kappa": h(1.0, (0.5, 2.0), b_i=0.05, alvo=0.70),
+            "cresc_expand": h(1.0, (0.5, 2.0), alvo=0.05),
+            "cresc_prune": h(1.0, (0.5, 2.0), alvo=0.02),
+        }
+
+    # ------------------------------------------------------------------
+    # TABELA: parâmetro → (sinal RM, medida PI) a partir do dicionário de
+    # telemetria bruta. Cada função é total (default neutro se faltar a
+    # métrica — sinal 0 = "não move", medida None = "PI não atua").
+    def _tabela_sinais(self) -> dict[str, tuple[Callable, Callable]]:
+        def f_sinal(chave, alvo, inverte=False):
+            def f(t):
+                if chave not in t:
+                    return 0.0
+                s = sinal_razao(t[chave], alvo)
+                return -s if inverte else s
+            return f
+
+        def f_medida(chave, alvo):
+            def f(t):
+                return float(t[chave]) if chave in t else None
+            return f
+
+        return {
+            # AdamW β₁ — proxy de curvatura: variância do gradiente padronizada
+            # já vem normalizada do produtor (var_grad_norm ∈ [0,∞), alvo 1.0)
+            "adamw_beta1": (f_sinal("var_grad_norm", 1.0),
+                            f_medida("var_grad_norm", 1.0)),
+            # AdamW β₂ — deriva do segundo momento (alvo 1.0 = estável);
+            # deriva ALTA ⟹ β₂ desce (sinal invertido: deriva alta ⟹ ↓β₂)
+            "adamw_beta2": (f_sinal("deriva_seg_momento", 1.0, inverte=True),
+                            f_medida("deriva_seg_momento", 1.0)),
+            # AdamW ε — razão ‖update‖/‖g‖ vs 1.0 (Teo 29.16)
+            "adamw_eps": (f_sinal("razao_update_grad", 1.0),
+                          f_medida("razao_update_grad", 1.0)),
+            # AdamW wd — norma L2 média vs 1.0: pesos pesados ⟹ wd sobe
+            "adamw_wd": (f_sinal("norma_peso", 1.0),
+                         f_medida("norma_peso", 1.0)),
+            # Muon momentum — ‖momentum‖/‖g‖ vs 1.0
+            "muon_momentum": (f_sinal("razao_momentum_grad", 1.0),
+                              f_medida("razao_momentum_grad", 1.0)),
+            # Muon escala — RMS(Muon)/RMS(AdamW) vs 1.0 (Teo 24.11)
+            "muon_escala": (f_sinal("razao_rms_mecanismos", 1.0),
+                            f_medida("razao_rms_mecanismos", 1.0)),
+            # τ_qk — controlado por ControladorBissecao (logit_max bruto)
+            "tau_qk": (lambda t: 0.0, f_medida("logit_max", 100.0)),
+            # PRS η_up — acerto acima do alvo ⟹ sobe mais agressivo
+            "prs_eta_up": (f_sinal("taxa_acerto_trust", 0.60),
+                           f_medida("taxa_acerto_trust", 0.60)),
+            # PRS η_down — acerto BAIXO ⟹ corta mais (sinal invertido)
+            "prs_eta_down": (f_sinal("taxa_acerto_trust", 0.60, inverte=True),
+                             f_medida("taxa_acerto_trust", 0.60)),
+            # PRS T_ciclo — progresso rápido (Δperda alto) ⟹ ciclo MAIOR
+            "prs_T_ciclo": (f_sinal("delta_perda_passo", 0.01),
+                            f_medida("delta_perda_passo", 0.01)),
+            "prs_decay_piso": (f_sinal("delta_perda_passo", 0.01),
+                               f_medida("delta_perda_passo", 0.01)),
+            # PRS percentil — clips acima do alvo 0.10 ⟹ percentil sobe
+            "prs_percentil": (f_sinal("razao_clip", 0.10),
+                              f_medida("razao_clip", 0.10)),
+            # PESO_MOE — razão L_moe/L_ce acima de 0.5 ⟹ peso desce
+            # (Teo 28.7-ii: CE é a descida primária)
+            "peso_moe": (None, None),   # tratado abaixo (sinal direto)
+            # PESO_SOM — ativação abaixo de 0.90 ⟹ peso sobe
+            "peso_som": (f_sinal("ativacao_som", 0.90),
+                         f_medida("ativacao_som", 0.90)),
+            # ABMO — folga da barreira: sinal já normalizado ±1
+            "abmo_margem": (f_sinal("margem_abmo_norm", 1.0),
+                            f_medida("margem_abmo_norm", 1.0)),
+            # CIAR κ — aceitação vs alvo
+            "ciar_kappa": (f_sinal("taxa_aceitacao_ciar", 0.70),
+                           f_medida("taxa_aceitacao_ciar", 0.70)),
+            # crescimento — expansão/poda vs alvos
+            "cresc_expand": (f_sinal("taxa_expansao", 0.05),
+                             f_medida("taxa_expansao", 0.05)),
+            "cresc_prune": (f_sinal("taxa_prune", 0.02),
+                            f_medida("taxa_prune", 0.02)),
+        }
+
+    # ------------------------------------------------------------------
+    def registrar(self, telemetria: dict) -> dict[str, float]:
+        """Um ciclo de ajuste: sinais → controladores → valores novos.
+
+        `telemetria` pode conter QUALQUER subconjunto das chaves —
+        parâmetros sem sinal simplesmente não movem (robustez)."""
+        self._passo += 1
+        if not self.ativo or (self._passo % self.a_cada) != 0:
+            return {k: self._valor(k) for k in self._controladores}
+        self._t_ajuste += 1
+        tabela = self._tabela_sinais()
+        valores: dict[str, float] = {}
+        for nome, ctl in self._controladores.items():
+            if isinstance(ctl, ControladorBissecao):
+                if "logit_max" in telemetria:
+                    ctl.atualizar(float(telemetria["logit_max"]))
+                valores[nome] = ctl.tau
+                if self.hub is not None:
+                    self.hub.atributo(f"autorreg_v17/{nome}", ctl.tau)
+                continue
+            sinal_fn, medida_fn = tabela[nome]
+            if nome == "peso_moe":
+                # sinal DIRETO: e = (alvo − razão)/alvo — acima do alvo ⟹ ↓
+                if "razao_moe_ce" in telemetria:
+                    r = float(telemetria["razao_moe_ce"])
+                    s = max(-1.0, min(1.0, (0.5 - r) / 0.5))
+                    medida = r
+                else:
+                    s, medida = 0.0, None
+            else:
+                s = float(sinal_fn(telemetria))
+                medida = medida_fn(telemetria)
+            ctl.atualizar(s, medida)
+            valores[nome] = ctl.valor
+            if self.hub is not None:
+                self.hub.atributo(f"autorreg_v17/{nome}", ctl.valor)
+                if ctl.e_anterior is not None:
+                    self.hub.atributo(f"autorreg_v17/{nome}__erro",
+                                      ctl.e_anterior)
+        return valores
+
+    def _valor(self, nome: str) -> float:
+        ctl = self._controladores[nome]
+        return ctl.tau if isinstance(ctl, ControladorBissecao) else ctl.valor
+
+    # ------------------------------------------------------------------
+    # ADAPTADORES de aplicação (escrita segura nos consumos)
+    def aplicar_em_otimizador(self, valores: dict, opt) -> list[str]:
+        """Escreve β₁/β₂/ε/wd (grupo AdamW), momentum/escala (Muon) e τ_qk
+        nos param_groups. Campos ausentes são ignorados (idempotente)."""
+        tocados = []
+        for grupo in getattr(opt, "param_groups", []):
+            if "adamw_beta1" in valores and "betas" in grupo:
+                b1 = max(0.0, min(0.999, valores["adamw_beta1"]))
+                b2 = max(b1, min(0.9999, valores.get("adamw_beta2",
+                                                     grupo["betas"][1])))
+                grupo["betas"] = (b1, b2)
+                tocados.append("betas")
+            if "adamw_eps" in valores and "eps" in grupo:
+                grupo["eps"] = float(max(1e-12, valores["adamw_eps"]))
+                tocados.append("eps")
+            if "adamw_wd" in valores and "weight_decay" in grupo:
+                grupo["weight_decay"] = float(max(0.0, valores["adamw_wd"]))
+                tocados.append("weight_decay")
+            if "muon_momentum" in valores and "momentum" in grupo:
+                grupo["momentum"] = float(max(0.0, min(0.999,
+                                                       valores["muon_momentum"])))
+                tocados.append("momentum")
+            if "muon_escala" in valores and "escala_muon" in grupo:
+                grupo["escala_muon"] = float(max(1e-3, valores["muon_escala"]))
+                tocados.append("escala_muon")
+            if "tau_qk" in valores and grupo.get("tau_qk", None):
+                grupo["tau_qk"] = float(valores["tau_qk"])
+                tocados.append("tau_qk")
+        return sorted(set(tocados))
+
+    def aplicar_em_prs(self, valores: dict, prs) -> list[str]:
+        """Escreve os 5 parâmetros do PRS V8 dentro dos limites seguros.
+        Atributos ausentes no objeto são ignorados (adapter tolerante)."""
+        mapa = {"prs_eta_up": "eta_up", "prs_eta_down": "eta_down",
+                "prs_T_ciclo": "T_ciclo", "prs_decay_piso": "decay_piso",
+                "prs_percentil": "percentil"}
+        tocados = []
+        for chave, attr in mapa.items():
+            if chave in valores and hasattr(prs, attr):
+                v = float(valores[chave])
+                if attr == "T_ciclo":
+                    v = max(1, int(round(v)))
+                setattr(prs, attr, v)
+                tocados.append(attr)
+        return sorted(set(tocados))
+
+    def telemetria(self) -> dict:
+        out = {}
+        for nome, ctl in self._controladores.items():
+            v = ctl.tau if isinstance(ctl, ControladorBissecao) else ctl.valor
+            out[f"autorreg_v17/{nome}"] = v
+        return out

src/khtst/aprimoramento/config.py

@@ -0,0 +1,107 @@
+# -*- coding: utf-8 -*-
+"""Configuração do pacote de APRIMORAMENTO KHTST (v17) — fonte única das
+constantes deste pacote (regra do projeto: nenhum número solto em módulos).
+
+Relação com khtst.config (produção): ESTE config é auto-contido e governa
+apenas o pacote `aprimoramento`. Os defaults respeitam a convenção de
+NASCIMENTO NEUTRO: com todos os flags em default, o comportamento é
+idêntico ao dos rascunhos de referência — cada aprimoramento novo entra
+com um campo próprio que pode ser desligado individualmente.
+
+CORREÇÕES de integração sobre o rascunho (defeitos D11/D12/D14 do doc 29):
+  • JEPAConfig.peso_var       — o peso 0.01 do hinge de variância era
+                                HARD-CODED no forward; agora é campo.
+  • JEPAConfig.ema_cosseno    — agenda de momentum EMA (BYOL) opt-in.
+  • QECTConfig.normalizar     — existia no rascunho e NUNCA era lido
+                                (campo morto); agora governa a normalização
+                                do QE (invariância de escala, Teo 29.4).
+  • QECTConfig.alpha/n_min    — significância estatística do "ganho real"
+                                (Teo 29.5 — Hoeffding) no lugar da conjunção
+                                de limiares fixos.
+  • DifusaoConfig.eta_lambda  — existia e NUNCA era lido; agora alimenta
+                                o AutoLambdaDiff (Teo 29.2).
+  • DifusaoConfig.rho_ancora  — âncora quadrática que dá ÓTIMO INTERIOR
+                                provado para λ_diff (Teo 29.2-iii).
+  • LambdaCConfig.modo/tau_eta— sinal suavizado (correção do defeito D6:
+                                a média da janela era computada e jogada
+                                fora) + agenda RM opcional (Teo 29.7-ii).
+  • TradeoffKConfig.estimar_C — constante de Zador estimada por OLS
+                                log-log (Teo 29.8) em vez de C=1 fixo.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+
+@dataclass
+class JEPAConfig:
+    dim: int = 256
+    pred_hidden: int = 512
+    ema_momentum: float = 0.996
+    ema_cosseno: bool = False      # Teo 29.12: agenda cosseno BYOL (opt-in)
+    lambda_jepa: float = 0.5       # peso do alinhamento (ANTES: campo morto)
+    peso_var: float = 0.01         # peso do hinge de variância (ANTES: fixo)
+    vicreg_lambda: float = 0.0     # >0 ativa o kernel Cython VICReg (cov)
+    vicreg_mu: float = 25.0
+    vicreg_gamma: float = 1.0
+    use_sg: bool = True            # stop-gradient no alvo (sempre recomendado)
+    normalize: bool = True         # L2-normaliza antes do MSE
+
+
+@dataclass
+class TradeoffKConfig:
+    d: int = 512                   # dimensão do codebook
+    n: int = 100_000               # amostras
+    lambda_c: float = 0.5
+    K_grid: tuple = (16, 32, 64, 128, 256, 512)
+    tol_rel: float = 0.05
+    metodo: Literal["rd", "asymp", "grid", "auto"] = "auto"
+    estimar_C: bool = True         # Teo 29.8: Ĉ por OLS log-log (default ON)
+    C_prior: float = 1.0           # prior de shrinkage para Ĉ (Teo 29.8-ii)
+    kappa_prior: int = 8           # peso do prior (n_C + κ — bias-variance)
+    bits_por_param: float = 16.0
+
+
+@dataclass
+class LambdaCConfig:
+    eta: float = 1e-3
+    lambda_c_min: float = 0.01
+    lambda_c_max: float = 0.99
+    janela: int = 100              # passos da média móvel do sinal (D6)
+    modo: Literal["alvo", "reversao"] = "alvo"
+    #   alvo     : delta = ε̄² − ε²_alvo        (rastreio de um alvo fixo)
+    #   reversao : delta = ε̄² − média_janela    (reversão à média da janela)
+    eta_agendado: bool = False     # Teo 29.7-ii: η_t = η₀/(1+t/τ) — RM q.c.
+    tau_eta: float = 400.0
+
+
+@dataclass
+class QECTConfig:
+    eps_qe: float = 1e-3
+    eps_ct: float = 1e-3
+    normalizar: bool = True        # AGORA USADO (D14): QE relativo a ‖x‖²
+    alpha: float = 0.05            # nível do teste unilateral (Teo 29.5)
+    n_min: int = 32                # amostras mínimas p/ declarar ganho real
+
+
+@dataclass
+class DifusaoConfig:
+    T: int = 1000
+    beta_start: float = 1e-4
+    beta_end: float = 0.02
+    lambda_diff: float = 0.1
+    eta_lambda: float = 0.05       # AGORA USADO (D14): passo do EG de λ_diff
+    rho_ancora: float = 1.0        # Teo 29.2-iii: âncora ρ(λ−λ₀)² (ótimo
+                                   # interior provado; 0 desliga a âncora)
+
+
+@dataclass
+class KHTSTConfig:
+    """Raiz do pacote — igual ao rascunho de referência + campos novos."""
+    jepa: JEPAConfig = field(default_factory=JEPAConfig)
+    k: TradeoffKConfig = field(default_factory=TradeoffKConfig)
+    lam: LambdaCConfig = field(default_factory=LambdaCConfig)
+    qect: QECTConfig = field(default_factory=QECTConfig)
+    diff: DifusaoConfig = field(default_factory=DifusaoConfig)
+    seed: int = 42

src/khtst/aprimoramento/controlador_hibrido.py

@@ -0,0 +1,208 @@
+# -*- coding: utf-8 -*-
+"""CONTROLADOR HÍBRIDO v17 — recursão unificada de autorregulação
+(doc 29 §§2 e 10; Teoremas 29.14–29.16).
+
+Recursão ÚNICA que governa todo parâmetro regulável θ (a mesma para os
+~20 parâmetros da tabela de sinais — AdamW, Muon, PRS V8, pesos de perda,
+ABMO, CIAR, crescimento):
+
+    u_{t+1} = Π_[u_min,u_max] ( u_t + a_t·s_t + b·e_t + c·Δe_t ),
+    θ_t     = θ₀ · exp(u_t),        a_t = a₀/(1 + t/τ_a),
+
+  • a_t·s_t  — termo ROBBINS–MONRO (aprendizado lento, ruído-tolerante).
+    Agenda a_t = a₀/(1+t/τ_a) satisfaz Σa_t = ∞ e Σa_t² < ∞ (Teo 28.5
+    reutilizado) — convergência q.c. ao ponto estacionário do campo.
+  • b·e_t    — termo INTEGRAL (PI): e_t = erro normalizado ao alvo.
+    Empurra θ para o ALVO declarado (rastreio de setpoint) — corrige
+    viés de regime que o sinal RM demoraria a integrar.
+  • c·Δe_t   — termo DERIVATIVO: Δe_t = e_t − e_{t−1}.
+
+DUAS PROVAS QUE JUSTIFICAM A FORMA (Teo 29.14):
+  (i) TELESCOPING do D-termo: Σ_{t≤T} c·Δe_t = c·(e_T − e_0) — a
+      contribuição CUMULATIVA do termo derivativo é limitada por
+      2c·sup|e| para TODO T, independentemente do horizonte. O D-termo
+      NUNCA desestabiliza a recursão (contrário do temor clássico).
+  (ii) DUAS ESCALAS (Borkar, Teo 28.6 generalizado): com a_t → 0
+      (escala LENTA) e ganhos b, c fixos (escala RÁPIDA), a dinâmica
+      separa: o laço PI rastreia o setpoint em tempo O(1) e o RM
+      converge sobre o equilíbrio já estabilizado. O erro estacionário
+      do laço PI com ganho b é |e_∞| = 0 para planta estática de
+      primeiro ordem com ganho finito (integral pura zera erro de
+      regime — argumento padrão de controle); o anti-windup (projeção +
+      congelamento do I fora da região segura) garante que o I-termo
+      não dispara além dos limites (Provar: u_t ∈ [u_min,u_max] ∀t por
+      indução — a projeção fecha a indução).
+
+SEPARAÇÃO HONESTA: o termo RM sozinho (v16) converge ao estacionário
+do CAMPO DE SINAIS, que pode ter viés de regime; o híbrido adiciona
+rastreio de setpoint EXPLÍCITO. Quem define o setpoint é a tabela de
+sinais (autorregulacao_estendida.py).
+"""
+from __future__ import annotations
+
+import math
+
+
+class ControladorHibrido:
+    """θ_t = θ₀·exp(u_t) com recursão mista RM + PI projetada.
+
+    Args:
+        centro: θ₀ — valor de NASCIMENTO NEUTRO (u=0 ⟹ θ=θ₀; todas as
+            constantes atuais de produção são os centros da tabela).
+        limites: (θ_min, θ_max) ABSOLUTOS — segurança estrutural.
+        a0, tau_a: agenda RM a_t = a0/(1+t/τ_a) (Σa=∞, Σa²<∞).
+        passo_max: |Δu| máximo por passo (segurança multiplicativa).
+        b_i, c_d: ganhos integral e derivativo (0 = RM puro, v16).
+        alvo: setpoint do erro (se medida for passada).
+        escala_e: divisor para normalizar o erro (default: |alvo|).
+        espera: passos de aquecimento antes do 1º ajuste (Teo 28.5-ii).
+    """
+
+    def __init__(self, centro: float, limites: tuple[float, float],
+                 a0: float = 0.05, tau_a: float = 400.0,
+                 passo_max: float = 0.05, b_i: float = 0.0, c_d: float = 0.0,
+                 alvo: float = 1.0, escala_e: float | None = None,
+                 espera: int = 0):
+        assert limites[0] <= centro <= limites[1], "centro fora dos limites"
+        self.centro = float(centro)
+        self.limites = (float(limites[0]), float(limites[1]))
+        self.a0 = float(a0)
+        self.tau_a = float(tau_a)
+        self.passo_max = float(passo_max)
+        self.b_i = float(b_i)
+        self.c_d = float(c_d)
+        self.alvo = float(alvo)
+        self.escala_e = float(escala_e) if escala_e else max(abs(alvo), 1e-9)
+        self.espera = int(espera)
+        self.t = 0
+        self.u = 0.0
+        self.e_anterior: float | None = None
+        self.i_acum = 0.0                  # anti-windup: I explícito e limitado
+
+    # ------------------------------------------------------------------
+    def erro(self, medida: float) -> float:
+        """e_t = (alvo − medida)/escala, clipado a ±2 (robustez a outliers)."""
+        e = (self.alvo - float(medida)) / self.escala_e
+        return max(-2.0, min(2.0, e))
+
+    def atualizar(self, sinal_rm: float, medida: float | None = None) -> float:
+        """Um passo da recursão híbrida (EXATAMENTE a forma do doc 29):
+
+            du = a_t·s_t + b·e_t + c·Δe_t     (POR PASSO — sem dupla
+            integração: o I é o próprio b·e_t per-step; Σb·e_t é o
+            integral implícito da recursão, não um termo extra)
+
+        Retorna θ_t. sinal_rm ∈ [−1,1] (positivo ↑ θ). `medida` ativa o
+        laço PI quando dado. Anti-windup: o termo b·e_t NÃO integra
+        quando u está colado na parede NA DIREÇÃO do erro (empurrar
+        além da projeção seria enrolar o integral)."""
+        sinal_rm = max(-1.0, min(1.0, float(sinal_rm)))
+        self.t += 1
+        if self.t <= self.espera:
+            return self.valor
+        a_t = self.a0 / (1.0 + self.t / self.tau_a)
+        du = a_t * sinal_rm
+
+        if medida is not None and (self.b_i != 0.0 or self.c_d != 0.0):
+            e = self.erro(medida)
+            de = 0.0 if self.e_anterior is None else (e - self.e_anterior)
+            self.e_anterior = e
+            u_max, u_min = self._u_max(), self._u_min()
+            # anti-windup direcional: integra só se empurra PARA DENTRO
+            pode_integrar = (e > 0 and self.u > u_min + 1e-12) or \
+                            (e < 0 and self.u < u_max - 1e-12) or e == 0.0
+            if pode_integrar:
+                du += self.b_i * e
+            self.i_acum += self.b_i * e          # telemetria do integral
+            i_max = 2.0 * abs(self.b_i) + 1e-12
+            self.i_acum = max(-i_max, min(i_max, self.i_acum))
+            du += self.c_d * de
+        elif medida is not None:
+            # sem ganhos PI: apenas registra o erro para telemetria
+            self.e_anterior = self.erro(medida)
+
+        du = max(-self.passo_max, min(self.passo_max, du))
+        self.u += du
+        self.u = max(self._u_min(), min(self._u_max(), self.u))
+        return self.valor
+
+    def _u_min(self) -> float:
+        return math.log(self.limites[0] / self.centro)
+
+    def _u_max(self) -> float:
+        return math.log(self.limites[1] / self.centro)
+
+    @property
+    def valor(self) -> float:
+        v = self.centro * math.exp(self.u)
+        # clamp final: exp(log(b)) arredonda a b+ε — a permanência no
+        # conjunto seguro é EXATA (Teo 29.14-ii sem épsilon de flutuante)
+        return min(max(v, self.limites[0]), self.limites[1])
+
+    def telemetria(self) -> dict:
+        return {"valor": self.valor, "u": self.u, "t": self.t,
+                "e": self.e_anterior, "i": self.i_acum}
+
+
+class ControladorBissecao:
+    """τ_qk por bisseção com banda-alvo (Teo 29.15).
+
+    Objetivo do usuário: manter o logit máximo ℓ_max na banda [lo, hi]
+    ajustando τ. Como o logit é LINEAR na escala de W_q (Teo 24.7 —
+    ℓ(γW) = γ·ℓ(W)), a correção multiplicativa exata é
+    τ ← τ·ℓ_alvo/ℓ_medida; com amortecimento η a convergência é
+    GEOMÉTRICA (razão |1−η| — mais forte que bisseção). O modo
+    "bissecao" puro mantém o colchete [τ_lo, τ_hi] e contrai pela
+    metade — erro ≤ (τ_max−τ_min)/2^k (forma do rascunho, mantida).
+    """
+
+    def __init__(self, tau_inicial: float = 100.0,
+                 banda: tuple[float, float] = (80.0, 120.0),
+                 modo: str = "escala", eta: float = 0.5,
+                 tau_limites: tuple[float, float] = (40.0, 400.0)):
+        self.tau = float(tau_inicial)
+        self.banda = (float(banda[0]), float(banda[1]))
+        self.modo = modo
+        self.eta = float(eta)
+        self.limites = (float(tau_limites[0]), float(tau_limites[1]))
+        # colchete do modo bisseção: [já-seguro, já-inseguro]
+        self._colchete = (self.limites[0], self.limites[1])
+        self.k = 0
+        self.historico: list[float] = []
+
+    def atualizar(self, logit_max: float) -> float:
+        """Um passo: recebe ℓ_max medido, devolve o novo τ."""
+        lo, hi = self.banda
+        alvo = 0.5 * (lo + hi)
+        l = max(float(logit_max), 1e-9)
+        if self.modo == "escala":
+            # correção exata amortecida (Teo 29.15-i): ℓ linear em τ ⟹
+            # a razão^η leva ao ponto fixo; η=1 corrige em 1 passo
+            razao = alvo / l
+            self.tau *= razao ** self.eta
+        else:
+            # bisseção honesta no colchete (semântica PÓS-CLIP — Teo 24.7:
+            # ℓ_observado = min(ℓ_natural, τ)):
+            #   ℓ > hi ⟹ τ ≥ ℓ > hi ⟹ τ ALTO demais ⟹ τ* está ABAIXO;
+            #   ℓ < lo ⟹ τ < lo (clip nem atuou nessa faixa) ⟹ τ* está ACIMA.
+            t_lo, t_hi = self._colchete
+            if l > hi:
+                t_hi = min(t_hi, self.tau)
+            elif l < lo:
+                t_lo = max(t_lo, self.tau)
+            else:
+                # dentro da banda: encolhe o colchete em torno de τ
+                t_lo, t_hi = max(t_lo, self.tau * 0.5), min(t_hi, self.tau * 2.0)
+            self._colchete = (max(t_lo, self.limites[0]),
+                              min(t_hi, self.limites[1]))
+            self.k += 1
+            self.tau = math.sqrt(self._colchete[0] * self._colchete[1])
+        self.tau = max(self.limites[0], min(self.limites[1], self.tau))
+        self.historico.append(self.tau)
+        if len(self.historico) > 512:
+            self.historico = self.historico[-256:]
+        return self.tau
+
+    def erro_colchete(self) -> float:
+        """Erro residual do colchete: ≤ (τ_max−τ_min)/2^k (Teo 29.15-ii)."""
+        return (self._colchete[1] - self._colchete[0]) / (2 ** max(1, self.k))

src/khtst/aprimoramento/difusao_gradiente.py

@@ -0,0 +1,243 @@
+# -*- coding: utf-8 -*-
+"""Difusão com gradiente — v17 refatorada (doc 29 §3).
+
+DDPM padrão com DUAS correções estruturais sobre o rascunho (defeitos
+D1/D2 do doc 29) e uma prova nova:
+
+D1 (CÓDIGO MORTO — defeito real): no rascunho, `lambda_diff` era um
+    nn.Parameter com requires_grad=False, `AutoLambdaDiff.step` NUNCA era
+    chamado por nenhum caminho, e `treinar_difusao` nem sequer usava
+    λ_diff na perda. O "autoajuste por gradiente sobre validação"
+    anunciado no docstring era ficção tripla. Aqui:
+      (a) a perda ponderada é L(λ) = λ·L_diff + ρ·(λ−λ₀)² — o hiper-
+          gradiente é EXATO por ser L AFIM em λ: ∂L/∂λ = L_diff + 2ρ(λ−λ₀)
+          (Teo 29.2-i: zero erro de estimação, sem diferenças finitas);
+      (b) com ρ>0 (âncora), L(λ) é ESTRITAMENTE CONVEXA em λ com ótimo
+          interior FECHADO: λ* = λ₀ − L_diff/(2ρ), clipado a [λmin,λmax]
+          (Teo 29.2-iii). Sem âncora, L é afim e o ótimo está SEMPRE na
+          borda — o EG empurraria λ para o limite e ficaria lá (a âncora
+          é o que torna o autoajuste não-trivial);
+      (c) a atualização multiplicativa λ ← λ·exp(−η·g) é descida de
+          gradiente EXPLICITEIRA (mirror descent com potencial entropia):
+          regret ≤ η·G²T/2 + ln(λmax/λmin)/η, optimizado em η=Θ(T^{−1/2})
+          ⟹ regret O(√T) — Teo 29.2-ii (Cesa-Bianchi & Lugosi, Cap. 2,
+          rederivado no doc 29 para o intervalo clipado).
+
+D2 (Polyak ausente): o rascunho amostra a rede crua. Aqui há EMA de
+    pesos opcional para amostragem/avaliação — Teo 29.3 (Polyak/Jensen):
+    para L convexa em θ, L(θ̄_T) ≤ (1/T)ΣL(θ_t) — a média nunca é pior
+    que a média das perdas e remove o ruído de alta frequência do
+    caminho SGD (variância do estimador reduzida pelo fator 1/(1−m)
+    do EMA; ver doc 29 §3.3).
+
+Corretude do núcleo DDPM (reprovada por completude, Teo 29.1):
+    q(x_t|x₀) = N(√ᾱ_t·x₀, (1−ᾱ_t)·I) por indução sobre ᾱ_t = ∏_{s≤t}α_s
+    (Ho et al. 2020, Lemma 1 — a perda ε é o limite variacional superior
+    reponderado; rederivação no doc 29 §3.1). O amostrador inverte a
+    média a posteriori q(x_{t−1}|x_t,x₀) com σ_t = √β_t.
+"""
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+from .config import DifusaoConfig
+
+
+class DenoiserMLP(nn.Module):
+    def __init__(self, dim: int, hidden: int = 512):
+        super().__init__()
+        self.t_proj = nn.Sequential(nn.Linear(1, hidden), nn.GELU(),
+                                    nn.Linear(hidden, hidden))
+        self.net = nn.Sequential(
+            nn.Linear(dim + hidden, hidden), nn.GELU(),
+            nn.Linear(hidden, hidden), nn.GELU(),
+            nn.Linear(hidden, dim),
+        )
+
+    def forward(self, x_t, t):
+        t_norm = t.float().unsqueeze(-1) / 1000.0
+        h_t = self.t_proj(t_norm)
+        return self.net(torch.cat([x_t, h_t], dim=-1))
+
+
+class DifusaoDDPM(nn.Module):
+    def __init__(self, dim: int, cfg: DifusaoConfig):
+        super().__init__()
+        self.cfg = cfg
+        self.net = DenoiserMLP(dim)
+        betas = torch.linspace(cfg.beta_start, cfg.beta_end, cfg.T)
+        alphas = 1.0 - betas
+        alpha_bar = torch.cumprod(alphas, dim=0)
+        self.register_buffer("betas", betas)
+        self.register_buffer("alphas", alphas)
+        self.register_buffer("alpha_bar", alpha_bar)
+        # D1 corrigido: λ_diff é um TENSOR PLANO governado pelo controlador
+        # (não parâmetro — autograd não devetocá-lo; o hipergradiente é
+        # EXATO e analítico: ∂L/∂λ = L_diff + 2ρ(λ−λ₀), Teo 29.2-i)
+        self.lambda_diff = torch.tensor(float(cfg.lambda_diff))
+        self.rho_ancora = float(cfg.rho_ancora)
+        self.lambda0 = float(cfg.lambda_diff)
+        # D2: EMA de pesos (Polyak) — nascimento neutro (default off)
+        self._ema: dict[str, torch.Tensor] | None = None
+
+    # -------------------------------------------------------------- núcleo
+    def q_sample(self, x0, t, noise=None):
+        if noise is None:
+            noise = torch.randn_like(x0)
+        ab = self.alpha_bar[t].view(-1, 1)
+        return ab.sqrt() * x0 + (1 - ab).sqrt() * noise, noise
+
+    def loss(self, x0: torch.Tensor) -> torch.Tensor:
+        """L_diff = E ‖ε − ε_θ(x_t, t)‖² (Teo 29.1)."""
+        B = x0.shape[0]
+        t = torch.randint(0, self.cfg.T, (B,), device=x0.device)
+        x_t, noise = self.q_sample(x0, t)
+        pred = self.net(x_t, t)
+        return F.mse_loss(pred, noise)
+
+    def loss_ponderada(self, x0: torch.Tensor) -> tuple[torch.Tensor, dict]:
+        """L(λ) = λ·L_diff + ρ·(λ−λ₀)² — AFIM + âncora em λ (Teo 29.2).
+
+        Devolve (perda escalável, telemetria com o hipergradiente EXATO).
+        O gradiente flui para a REDE por λ·L_diff e para λ pelo ramo da
+        âncora (implementado como tensor com requires_grad no caminho)."""
+        lam = torch.tensor(float(self.lambda_diff), requires_grad=True)
+        l_diff = self.loss(x0)
+        l_total = lam * l_diff
+        if self.rho_ancora > 0:
+            l_total = l_total + self.rho_ancora * (lam - self.lambda0) ** 2
+        # hipergradiente EXATO (sem autograd no λ — forma fechada):
+        g = float(l_diff.detach()) + 2.0 * self.rho_ancora \
+            * (float(lam.detach()) - self.lambda0)
+        return l_total, {"lambda_diff": float(lam.detach()),
+                         "hipergradiente": g,
+                         "perda_difusao": float(l_diff.detach())}
+
+    @torch.no_grad()
+    def sample(self, shape, device="cpu"):
+        x = torch.randn(shape, device=device)
+        for t in reversed(range(self.cfg.T)):
+            tt = torch.full((shape[0],), t, device=device, dtype=torch.long)
+            eps = self.net(x, tt)
+            a, ab = self.alphas[t], self.alpha_bar[t]
+            x = (x - (1 - a) / (1 - ab).sqrt() * eps) / a.sqrt()
+            if t > 0:
+                x = x + self.betas[t].sqrt() * torch.randn_like(x)
+        return x
+
+    # ------------------------------------------------ D2: EMA (Polyak) ----
+    @torch.no_grad()
+    def ema_atualizar(self, m: float = 0.999) -> float:
+        """EMA dos pesos do denoiser (Teo 29.3 — Polyak)."""
+        if self._ema is None:
+            self._ema = {k: v.detach().clone()
+                         for k, v in self.net.state_dict().items()}
+            return m
+        for k, v in self.net.state_dict().items():
+            if v.dtype.is_floating_point:
+                self._ema[k].mul_(m).add_(v.detach(), alpha=1.0 - m)
+            else:
+                self._ema[k].copy_(v)
+        return m
+
+    @torch.no_grad()
+    def carregar_ema(self) -> bool:
+        """Promove os pesos EMA a pesos correntes (avaliação/amostragem)."""
+        if not self._ema:
+            return False
+        self.net.load_state_dict(self._ema)
+        return True
+
+
+# ------------------------- autoajuste de λ_diff (D1 VIVO) -----------------
+
+@dataclass
+class AutoLambdaDiff:
+    """Descida multiplicativa (EG) de λ com hipergradiente EXATO + âncora.
+
+    Atualização: λ ← clip( λ·exp(−η·g), λmin, λmax ),
+        g = L_diff + 2ρ(λ−λ₀)     (Teo 29.2-i — EXATO, L afim+quadrática)
+
+    Teo 29.2-ii (regret do EG, intervalo clipado): para L convexa com
+    |∂L/∂λ| ≤ G e λ ∈ [λmin,λmax], o regret cumulativo obedece
+        R_T ≤ η·G²·T/2 + ln(λmax/λmin)/η  ≤ G·√(2·T·ln(λmax/λmin))
+    com η* = √(2·ln(λmax/λmin)/(G²T) — perda média ≤ ótimo + O(1/√T).
+    Teo 29.2-iii: com ρ>0, λ* = clip(λ₀ − L_diff/(2ρ)) é o ÚNICO
+    minimizador (L''=2ρ>0) — o controlador tem ÓTIMO INTERIOR provado
+    e o EG converge para a sua vizinhança O(η·G).
+    """
+
+    def __init__(self, valor_inicial: float, eta: float = 0.05,
+                 rho_ancora: float = 1.0, lambda0: float | None = None,
+                 limites: tuple[float, float] = (1e-4, 1.0)):
+        self.valor = float(valor_inicial)
+        self.eta = float(eta)
+        self.rho = float(rho_ancora)
+        self.lambda0 = float(lambda0) if lambda0 is not None else self.valor
+        self.limites = (float(limites[0]), float(limites[1]))
+        self.historico: list[float] = [self.valor]
+
+    def passo_analitico(self, l_diff: float) -> float:
+        """Passo FECHADO (âncora ρ>0): vai direto ao λ* clipado.
+        λ* = λ₀ − L_diff/(2ρ) — minimizador exato de L(λ) (Teo 29.2-iii).
+        Custo O(1), sem taxa de aprendizado — preferível quando a âncora
+        está ativa e L_diff é estável na janela."""
+        if self.rho <= 0:
+            return self.passo_eg(l_diff)
+        alvo = self.lambda0 - float(l_diff) / (2.0 * self.rho)
+        self.valor = max(self.limites[0], min(self.limites[1], alvo))
+        self.historico.append(self.valor)
+        return self.valor
+
+    def passo_eg(self, grad_lambda: float) -> float:
+        """Passo EG multiplicativo (Teo 29.2-ii) — usado com ρ=0 ou como
+        suavização. grad_lambda = ∂L/∂λ (exato pela forma fechada)."""
+        self.valor *= math.exp(-self.eta * float(grad_lambda))
+        self.valor = max(self.limites[0], min(self.limites[1], self.valor))
+        self.historico.append(self.valor)
+        return self.valor
+
+    # compatibilidade com o rascunho (assinatura antiga `step`)
+    def step(self, grad_lambda: float) -> float:
+        return self.passo_eg(grad_lambda)
+
+
+def treinar_difusao(
+    modelo: DifusaoDDPM,
+    data: torch.Tensor,
+    passos: int = 2000,
+    lr: float = 1e-3,
+    device: str = "cpu",
+    ema: float = 0.0,            # D2: >0 ativa EMA (default off = rascunho)
+    lambda_auto: AutoLambdaDiff | None = None,   # D1: λ vivo opt-in
+    a_cada: int = 50,
+) -> list[float]:
+    """Loop de treino real com gradiente + autoajuste de λ vivo (D1).
+
+    λ_diff entra na perda via loss_ponderada; a cada `a_cada` passos o
+    controlador recebe o hipergradiente EXATO (Teo 29.2-i)."""
+    modelo.to(device).train()
+    opt = torch.optim.AdamW(modelo.net.parameters(), lr=lr)
+    historico: list[float] = []
+    for i in range(passos):
+        idx = torch.randint(0, data.shape[0], (64,), device=device)
+        x0 = data[idx].to(device)
+        if lambda_auto is not None:
+            l_total, tele = modelo.loss_ponderada(x0)
+            modelo.lambda_diff = torch.tensor(tele["lambda_diff"])
+            if (i + 1) % a_cada == 0:
+                lambda_auto.passo_analitico(tele["perda_difusao"])
+        else:
+            l_total = modelo.loss(x0)
+        opt.zero_grad(set_to_none=True)
+        l_total.backward()
+        opt.step()
+        if ema > 0:
+            modelo.ema_atualizar(ema)
+        historico.append(float(l_total.detach()))
+    return historico

src/khtst/aprimoramento/jepa.py

@@ -0,0 +1,237 @@
+# -*- coding: utf-8 -*-
+"""JEPA — v17 refatorada (doc 29 §7). Quatro correções sobre o rascunho:
+
+D10 (CONDICIONAL MORTO): `z_t_p = self._project(z_t) if self.cfg.use_sg
+    else self._project(z_t)` — os DOIS ramos eram idênticos. Removido;
+    o stop-gradient é aplicado UMA vez, explicitamente.
+
+D11 (VARIÂNCIA AGRUPADA — anti-colapso fraco): o rascunho calculava
+    `z.var(dim=(-2,-1))` — variância POOLADA sobre (T,D) e depois
+    média no lote. O hinge de VICReg é POR DIMENSÃO. Teo 29.10 (Jensen):
+        E_dims[relu(γ − σ_j)] ≥ relu(γ − E_dims[σ_j])
+    — o hinge POR DIMENSÃO é SEMPRE ≥ o poolado, com desigualdade
+    ESTRITA quando as dimensões têm desvios heterogêneos. Contraexemplo
+    concreto: dims com σ = (2, 0) — a variância poolada é grande, o
+    hinge poolado vale 0 e a dimensão B colapsada fica INVISÍVEL; o
+    per-dimensão cobra relu(1−0) = 1 dela. O colapso parcial (pior
+    caso prático — dims mortas que carregam informação perdida) só é
+    visto pelo per-dimensão.
+
+D12 (TRUNCAMENTO DE COMPRIMENTO): o rascunho truncava para
+    L = min(Tc, Tt) — descartava a energia das posições além de L.
+    Correção (Teo 29.11): pooling adaptativo por média para o
+    comprimento comum — projeção L2 sobre o espaço mais grosso
+    (P² = P, P = Pᵀ ⟹ não-expansiva: ‖Pz‖ ≤ ‖z‖). O truncamento tem
+    erro de descarte E_trunc = Σ_{t>L}‖z_t‖²/E‖z‖² ≥ 0 enquanto o
+    pooling tem erro de resolução — dominado pelo de descarte quando
+    a energia é espalhada (caso típico de representações treinadas).
+
+D13 (PESOS MORTOS): `cfg.lambda_jepa` (0.5) existia no config e NUNCA
+    era usado; o peso da variância era 0.01 hard-coded. Agora:
+        L_total = λ_jepa·L_alinhamento + peso_var·L_variância
+    com os dois pesos lidos do config (nascimento neutro: os defaults
+    λ=0.5, peso_var=0.01 reproduzem o rascunho quando λ_jepa=1 ... e o
+    caso λ=0.5 é o novo default DOCUMENTADO — o comportamento do
+    rascunho corresponde a λ_jepa=1.0, que o teste de regressão fixa).
+
+Teo 29.12 (EMA cosseno — opt-in): m_t = 1 − (1−m₀)·(cos(πt/T)+1)/2
+    nasce em m₀ (alvo segue o encoder no arranque) e cresce
+    monotonamente até 1 (alvo congela quando a representação já
+    convergiu). Variância do ruído do alvo por passo: σ²_eff =
+    ((1−m)/(1+m))·σ² — DECREASE com m (alvo mais silencioso no fim).
+
+Teo 29.13 (COLAPSO NÃO É MÍNIMO LOCAL): no ponto colapsado (z constante),
+    o MSE é plano a 1ª ordem mas o hinge de variância está no MÁXIMO
+    (σ_j=0 ⟹ relu(γ−0)=γ) e qualquer perturbação o diminui ⟹ o colapso
+    não é mínimo local de L_total e a descida escapa. HONESTIDADE: em
+    σ=0 exato há kink (subdiferencial) — o autograd pode dar 0 no ponto
+    exato; a fuga é geométrica e a produção empurra a direção
+    explicitamente (yc/σ² do FunilLatente). peso_var > 0 é NECESSÁRIO.
+
+Cython prioritário (requisito do projeto): quando `cfg.vicreg_lambda>0`
+    e o kernel compilado `khtst.treino.jepa_cython.vicreg_cython`
+    estiver disponível, o termo VICReg completo (invariância + variância
+    + covariância) é delegado a ele; fallback PyTorch honesto.
+"""
+from __future__ import annotations
+
+import copy
+import math
+from typing import Optional
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+from .config import JEPAConfig
+
+try:  # Cython prioritário — a ponte tem fallback PyTorch com as MESMAS
+    # convenções (import da ponte, não do kernel cru: degradação honesta)
+    from khtst.treino.jepa_cython import vicreg_cython as _vicreg_kernel
+    _TEM_VICREG = True
+except Exception:                                        # pragma: no cover
+    _vicreg_kernel = None
+    _TEM_VICREG = False
+
+
+class MLP(nn.Module):
+    def __init__(self, dim_in: int, dim_hidden: int, dim_out: int):
+        super().__init__()
+        self.net = nn.Sequential(
+            nn.Linear(dim_in, dim_hidden),
+            nn.GELU(),
+            nn.LayerNorm(dim_hidden),
+            nn.Linear(dim_hidden, dim_hidden),
+            nn.GELU(),
+            nn.Linear(dim_hidden, dim_out),
+        )
+
+    def forward(self, x):
+        return self.net(x)
+
+
+class Encoder(nn.Module):
+    """Encoder genérico — substitua por Mamba-3 + atenção em produção."""
+
+    def __init__(self, vocab: int, dim: int, n_layers: int = 4):
+        super().__init__()
+        self.emb = nn.Embedding(vocab, dim)
+        self.layers = nn.ModuleList([
+            nn.TransformerEncoderLayer(
+                d_model=dim, nhead=4, dim_feedforward=dim * 4,
+                batch_first=True, activation="gelu",
+            ) for _ in range(n_layers)
+        ])
+        self.norm = nn.LayerNorm(dim)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        h = self.emb(x)
+        for layer in self.layers:
+            h = layer(h)
+        return self.norm(h)
+
+
+# ------------------------------ termo de variância --------------------------
+
+def hinge_variancia_por_dim(z: torch.Tensor, gamma: float = 1.0) -> torch.Tensor:
+    """Teo 29.10 — hinge de variância POR DIMENSÃO (anti-colapso forte).
+
+    z: (B, T, D) — achata para (B·T, D) e calcula σ_j por dimensão j
+    sobre o lote-tempo (populacional, correção=0 — mesma convenção
+    anti-NaN da v15.1: lote 1 não divide por zero)."""
+    flat = z.reshape(-1, z.shape[-1])
+    std = flat.std(dim=0, correction=0) + 1e-4
+    return F.relu(gamma - std).mean()
+
+
+# ---------------------------------- JEPA ------------------------------------
+
+class JEPA(nn.Module):
+    """Joint Embedding Predictive Architecture (v17)."""
+
+    def __init__(self, encoder: nn.Module, cfg: JEPAConfig):
+        super().__init__()
+        self.cfg = cfg
+        self.online = encoder
+        self.target = copy.deepcopy(encoder)
+        for p in self.target.parameters():
+            p.requires_grad_(False)
+        self.predictor = MLP(cfg.dim, cfg.pred_hidden, cfg.dim)
+        self.pos_proj = nn.Linear(cfg.dim, cfg.dim)
+        self._t_ema = 0
+
+    @torch.no_grad()
+    def update_target(self):
+        m = self.momentum_efetivo()
+        for po, pt in zip(self.online.parameters(), self.target.parameters()):
+            pt.mul_(m).add_(po.detach(), alpha=1.0 - m)
+        for bo, bt in zip(self.online.buffers(), self.target.buffers()):
+            bt.copy_(bo)
+
+    def momentum_efetivo(self) -> float:
+        """Teo 29.12 — agenda cosseno BYOL (opt-in) ou momentum fixo."""
+        m0 = self.cfg.ema_momentum
+        if not self.cfg.ema_cosseno:
+            return m0
+        # horizonte default: 100k passos (doc 29 §7.5); monótona m₀→1
+        T_h = 100_000
+        return 1.0 - (1.0 - m0) * (math.cos(math.pi * min(1.0, self._t_ema / T_h)) + 1.0) / 2.0
+
+    def _project(self, z: torch.Tensor) -> torch.Tensor:
+        return F.normalize(z, dim=-1) if self.cfg.normalize else z
+
+    @staticmethod
+    def _alinhar_comprimento(z_hat: torch.Tensor,
+                             z_t: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:
+        """Teo 29.11 — pooling adaptativo (substitui o truncamento D12)."""
+        if z_hat.shape[1] == z_t.shape[1]:
+            return z_hat, z_t
+        L = min(z_hat.shape[1], z_t.shape[1])
+        # (B, T, D) → (B, D, T) → avg_pool1d → (B, D, L) → (B, L, D)
+        def pool(z):
+            return F.adaptive_avg_pool1d(z.transpose(1, 2), L).transpose(1, 2)
+        return pool(z_hat), pool(z_t)
+
+    def forward(
+        self,
+        ctx: torch.Tensor,
+        tgt: torch.Tensor,
+        pos_emb: Optional[torch.Tensor] = None,
+    ) -> dict:
+        cfg = self.cfg
+        z_c = self.online(ctx)                    # (B, Tc, D)
+        # D10 corrigido: stop-gradient explícito e ÚNICO (o rascunho tinha
+        # um condicional com os dois ramos idênticos)
+        with torch.no_grad():
+            z_t = self.target(tgt)                # (B, Tt, D)
+        z_t_p = self._project(z_t)
+
+        if pos_emb is None:
+            pos_emb = torch.zeros_like(z_c)
+        else:
+            pos_emb = self.pos_proj(pos_emb)
+
+        z_hat = self.predictor(z_c + pos_emb)     # (B, Tc, D)
+        z_hat_p = self._project(z_hat)
+
+        # D12 corrigido: pooling adaptativo em vez de truncamento
+        z_hat_p, z_t_p = self._alinhar_comprimento(z_hat_p, z_t_p)
+
+        # D13 corrigido: pesos do CONFIG (λ_jepa era campo morto; 0.01
+        # era constante solta — agora peso_var do config)
+        mse = F.mse_loss(z_hat_p, z_t_p)
+        var_hat = hinge_variancia_por_dim(z_hat_p, 1.0)
+        var_tgt = hinge_variancia_por_dim(z_t_p, 1.0)
+        var_loss = var_hat + var_tgt
+
+        total = cfg.lambda_jepa * mse + cfg.peso_var * var_loss
+
+        # Cython prioritário: VICReg completo (invariância+var+cov) opt-in
+        vic_tele: dict = {}
+        if cfg.vicreg_lambda > 0.0 and _TEM_VICREG:
+            B, T, D = z_hat_p.shape
+            P = z_hat_p.reshape(-1, D)
+            Z = z_t_p.reshape(-1, D)
+            try:
+                L_v, partes = _vicreg_kernel(P, Z, 1.0, cfg.vicreg_mu,
+                                             cfg.vicreg_gamma)
+                total = total + cfg.vicreg_lambda * L_v
+                vic_tele = dict(partes)
+            except Exception as e:                # pragma: no cover
+                vic_tele = {"motor": "fallback", "erro": str(e)}
+
+        # Teo 29.13 — telemetria do colapso: variância média por dimensão
+        with torch.no_grad():
+            std_por_dim = z_hat_p.reshape(-1, z_hat_p.shape[-1]).std(0, correction=0)
+            frac_colapsada = float((std_por_dim < 1e-2).float().mean())
+
+        self._t_ema += 1
+        return {"loss": total, "mse": mse.detach(), "var": var_loss.detach(),
+                "mu_ema": self.momentum_efetivo(),
+                "frac_colapsada": frac_colapsada,
+                "cython": _TEM_VICREG, **vic_tele}
+
+    def training_step(self, ctx, tgt, pos_emb=None) -> dict:
+        out = self.forward(ctx, tgt, pos_emb)
+        self.update_target()
+        return out

src/khtst/aprimoramento/lambda_c_unificado.py

@@ -0,0 +1,147 @@
+# -*- coding: utf-8 -*-
+"""Autoajuste unificado de λ_c — v17 refatorada (doc 29 §5).
+
+Elimina divergência entre caminho Cython (rápido) e Python (referência).
+Fonte única: este módulo. `patches/correcoes.py` mantém a EQUAÇÃO
+ESPECTRAL (intervalo do joelho — v15.1); ESTE módulo é o CONTROLADOR
+TEMPORAL que rastreia o alvo ao longo do treino — as duas camadas são
+complementares e a suíte v17 testa as duas.
+
+Regra (v17, com os DOIS defeitos do rascunho corrigidos):
+
+    λ_c(t+1) = clip( λ_c(t) · exp( −η_t · Δ(t) ),  λ_min, λ_max )
+
+    D6 (SINAL MORTO — defeito real): o rascunho computava a média móvel
+    `media` da janela e NUNCA a usava — o delta era o ε² INSTANTÂNEO,
+    com toda a variância amostral do passo. Correção (Teo 29.7-i):
+        modo="alvo":     Δ(t) = ε̄²(t) − ε²_alvo
+        modo="reversao": Δ(t) = ε̄²(t) − média_janela(ε²)
+    com ε̄²(t) = média móvel da janela `janela`. REDUÇÃO DE VARIÂNCIA
+    provada: para amostras i.i.d. com variância σ², Var(média de W) =
+    σ²/W (Teo 29.7-i) — o sinal do controlador fica W vezes mais
+    quieto sem viés (média não-enviesada); Chebyshev:
+    P(|ε̄²−μ|>t) ≤ σ²/(W·t²).
+
+    D7 (PASSO CONSTANTE): η fixo só garante convergência a uma
+    VIZINHANÇA O(η) do ponto fixo. Correção (Teo 29.7-ii): modo
+    `eta_agendado=True` usa η_t = η₀/(1+t/τ) — satisfaz Ση_t = ∞ e
+    Ση_t² < ∞ ⟹ convergência q.c. (Robbins–Monro; Teo 28.5 reutilizado
+    — o campo de deriva b(u) = −η₀·Δ(ε̄²(u)) é Lipschitz no compacto
+    [λmin,λmax] e o ruído tem segundo momento finito).
+
+Caminhos `fast_path_step`/`ref_path_step`: ref DELEGA a fast —
+identidade bit-a-bit POR CONSTRUÇÃO, verificada numericamente a cada
+suíte (n passos, max_diff == 0.0). A verificação SHA-256 das fontes é
+mantida como auditoria (avisa divergência de arquivos, não é teste
+matemático).
+"""
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass, field
+from typing import Deque
+
+import numpy as np
+
+from .config import LambdaCConfig
+
+
+@dataclass
+class EstadoLambdaC:
+    valor: float = 0.5
+    historico: Deque[float] = field(default_factory=lambda: deque(maxlen=1000))
+    eps_medio: Deque[float] = field(default_factory=lambda: deque(maxlen=100))
+    passo: int = 0
+
+
+class AutoAjusteLambdaC:
+    """Controlador temporal de λ_c com sinal suavizado VIVO (D6 corrigido)."""
+
+    def __init__(self, cfg: LambdaCConfig, eps_target: float = 1e-3):
+        self.cfg = cfg
+        self.eps_target = eps_target
+        self.estado = EstadoLambdaC(valor=0.5)
+
+    def step(self, eps2: float) -> float:
+        """Um passo com o sinal da média da janela (Teo 29.7-i).
+
+        Regressão do defeito: no rascunho, `media` era calculada e o
+        delta usava `eps2` cru — a suíte v17 prova que, com janela cuja
+        média difere do instante, ESTE controlador responde à média."""
+        cfg = self.cfg
+        self.estado.eps_medio.append(float(eps2))
+        if len(self.estado.eps_medio) >= cfg.janela:
+            media = float(np.mean(self.estado.eps_medio))
+            if cfg.modo == "reversao":
+                # reversão à média da janela: o INSTANTÂNEO acima da média
+                # da janela empurra λ para baixo (e vice-versa)
+                delta = float(eps2) - media
+            else:
+                # modo alvo: sinal SUAVIZADO (média da janela) vs alvo fixo
+                delta = media - self.eps_target
+            if cfg.eta_agendado:
+                self.estado.passo += 1
+                eta_t = cfg.eta / (1.0 + self.estado.passo / cfg.tau_eta)
+            else:
+                eta_t = cfg.eta
+            novo = self.estado.valor * float(np.exp(-eta_t * delta))
+            novo = float(np.clip(novo, cfg.lambda_c_min, cfg.lambda_c_max))
+            self.estado.valor = novo
+        self.estado.historico.append(self.estado.valor)
+        return self.estado.valor
+
+
+# ------------------------- caminhos rápidos (equivalência) -----------------
+
+def fast_path_step(lambda_prev: float, eps2: float, eps_target: float,
+                   eta: float, lo: float, hi: float) -> float:
+    """Compilável com @cython.boundscheck(False). Aqui: numpy puro."""
+    delta = eps2 - eps_target
+    novo = lambda_prev * np.exp(-eta * delta)
+    if novo < lo:
+        novo = lo
+    if novo > hi:
+        novo = hi
+    return float(novo)
+
+
+def ref_path_step(lambda_prev: float, eps2: float, eps_target: float,
+                  eta: float, lo: float, hi: float) -> float:
+    """Referência Python — bit-a-bit idêntico ao fast (delega)."""
+    return fast_path_step(lambda_prev, eps2, eps_target, eta, lo, hi)
+
+
+# ------------------------------- auditoria --------------------------------
+
+def sha256(path: str) -> str:
+    import hashlib
+    import pathlib
+    return hashlib.sha256(pathlib.Path(path).read_bytes()).hexdigest()
+
+
+def verificar_equivalencia_fontes(caminho_patch: str, caminho_quanta: str,
+                                  caminho_jepa: str) -> dict:
+    """Compara SHA-256 dos três arquivos (AUDITORIA de integridade —
+    avisa divergência; o teste matemático canônico é o numérico abaixo)."""
+    hashes = {
+        "patch": sha256(caminho_patch),
+        "quanta": sha256(caminho_quanta),
+        "jepa": sha256(caminho_jepa),
+    }
+    ok = len(set(hashes.values())) == 1
+    return {"ok": ok, **hashes}
+
+
+def equivalencia_numerica(n: int = 10_000, seed: int = 42) -> dict:
+    """Roda n passos em ambos caminhos e compara bit-a-bit (Teo 29.7-iii:
+    a equivalência é POR CONSTRUÇÃO — ref delega a fast; o teste fixa a
+    propriedade contra regressões de refatoração)."""
+    rng = np.random.default_rng(seed)
+    lam_f, lam_r = 0.5, 0.5
+    max_diff = 0.0
+    for _ in range(n):
+        eps2 = float(rng.uniform(1e-5, 1e-2))
+        lam_f = fast_path_step(lam_f, eps2, 1e-3, 1e-3, 0.01, 0.99)
+        lam_r = ref_path_step(lam_r, eps2, 1e-3, 1e-3, 0.01, 0.99)
+        max_diff = max(max_diff, abs(lam_f - lam_r))
+    return {"passos": n, "max_diff": max_diff, "identico": max_diff == 0.0}

src/khtst/aprimoramento/metricas_qe_ct.py

@@ -0,0 +1,191 @@
+# -*- coding: utf-8 -*-
+"""Métricas QE + CT — v17 refatorada (doc 29 §4).
+
+Substitutos do Erro Topológico (TE) com TRÊS correções sobre o rascunho
+(defeitos D3/D4/D5 do doc 29):
+
+D3 (ESCALA DEPENDENTE DA DIMENSÃO): o CT do rascunho somava ‖Δz‖² sobre
+    TODOS os eixos (B·D), logo crescia linearmente com B e D — dois
+    experimentos com dimensões diferentes eram incomparáveis. Correção
+    (Teo 29.4): CT_norm = Σ_t w_t·‖z_t − z_{t−1}‖²/(B·D) — energia de
+    deriva POR COORDENADA, invariante a mudança de lote/dimensão.
+    Prova da invariância: com z' = reindexação de z em (T, B'·D'),
+    ‖Δz'‖² = (B'D'/BD)·‖Δz‖² (partição das coordenadas) ⟹ o quociente
+    é idêntico — CT_norm não vê a fatoração do eixo de características.
+
+D4 (CONJUNÇÃO SEM SIGNIFICÂNCIA): `ganho = (Δ_QE < −ε) and (Δ_CT < −ε)`
+    com ε fixo é um teste de hipótese implícito SEM nível controlado —
+    com N amostras ruidosas, a taxa de falso-positivo não é limitada.
+    Correção (Teo 29.5): declara ganho real só se o limite superior de
+    confiança 1−α_f da MÉDIA de cada delta for < 0:
+        Student-t (default): UCB(Δ̄) = Δ̄_N + t_{1−α_f,N−1}·s/√N
+            — válido assintoticamente pelo TCL, sem suposição de suporte;
+        Hoeffding (opcional, raio DECLARADO R no config):
+            UCB(Δ̄) = Δ̄_N + R·√(ln(1/α_f)/(2N)) — válido em amostra
+            finita SE R ≥ range verdadeiro (suposição explícita; usar o
+            range OBSERVADO NÃO é válido — subestima o suporte).
+    α_f = α/2 (União de Bonferroni): P(falso ganho) ≤ 2·α_f = α
+    (Teo 29.5-i). Complexidade de amostra (Teo 29.5-ii): para detectar
+    efeito t sob Hoeffding é preciso N ≥ R²·ln(1/α_f)/(2t²) — o `n_min`
+    do cfg implementa o piso mínimo declarado.
+
+D5 (te_antigo O(N·G)): a distância de cada amostra a TODOS os centros
+    da grade era O(N·G). Correção: scipy.spatial.cKDTree — consulta
+    O(log G) por amostra, O(N·log G) total (Teo 29.6-i). Equivalência
+    de resultado: para centro mínimo ÚNICO, a consulta devolve o MESMO
+    índice do argmin (Teo 29.6-ii); empates têm medida zero sob grades
+    com perturbação contínua — e a versão KDTree documenta o tie-break.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from .config import QECTConfig
+
+
+@dataclass
+class ResultadoQECT:
+    qe: float
+    ct: float
+    ganho_real: bool
+    delta_qe: float
+    delta_ct: float
+    # v17 — telemetria do teste de significância (Teo 29.5)
+    ucb_qe: float = 0.0
+    ucb_ct: float = 0.0
+    significativo: bool = False
+    n_amostras: int = 0
+
+
+def erro_quantizacao(x: np.ndarray, x_hat: np.ndarray,
+                     normalizar: bool = False) -> float:
+    """QE = (1/N)·Σ‖x − x̂‖²; com normalizar=True: QE/mean‖x‖² (D14 vivo).
+
+    Teo 29.4-i (invariância de escala): QE(αx, αx̂) = α²·QE(x, x̂) — o
+    QE relativo QE/mean‖x‖² é INVARIANTE a reescala global dos dados,
+    permitindo comparar camadas/épocas com energias distintas."""
+    assert x.shape == x_hat.shape, f"shapes {x.shape} vs {x_hat.shape}"
+    qe = float(np.mean(np.sum((x - x_hat) ** 2, axis=-1)))
+    if normalizar:
+        escala = float(np.mean(np.sum(x ** 2, axis=-1))) + 1e-12
+        qe = qe / escala
+    return qe
+
+
+def consistencia_temporal(z: np.ndarray,
+                          ocupacao: np.ndarray | None = None,
+                          por_coordenada: bool = True) -> float:
+    """CT — deriva temporal ponderada por ocupação dos clusters.
+
+    z: (T, B, D) — representações latentes ao longo do tempo.
+    ocupacao: (T,) — ocupação do cluster em cada passo (padrão: uniforme).
+
+    v17 (Teo 29.4): por_coordenada=True divide por (B·D) — energia de
+    deriva POR COORDENADA, comparável entre configurações (correção D3).
+    O default preserva o valor ABSOLUTO do rascunho (comparabilidade de
+    regressão); os testes de ganho (avaliar_ganho) usam o normalizado.
+    """
+    T = z.shape[0]
+    if ocupacao is None:
+        ocupacao = np.ones(T, dtype=float)
+    w = ocupacao / (ocupacao.sum() + 1e-12)
+    drifts = np.sum((z[1:] - z[:-1]) ** 2, axis=(-1, -2))  # (T-1,)
+    ct = float(np.sum(w[1:] * drifts))
+    if por_coordenada:
+        # Teo 29.4-ii: média POR COORDENADA — os pesos w já normalizam o
+        # eixo temporal (Σw=1), resta dividir por B·D (NÃO por (T−1)·B·D)
+        ct = ct / max(z.shape[1] * z.shape[2], 1)
+    return ct
+
+
+def _ucb_media(deltas: np.ndarray, alpha_f: float,
+               raio_declarado: float | None = None) -> float:
+    """UCB 1−α_f da média (Teo 29.5).
+
+    Default: Student-t — UCB = Δ̄ + t_{1−α_f,N−1}·s/√N (TCL; sem
+    suposição de suporte; honesto para N ≥ n_min). Se `raio_declarado`
+    for passado, usa Hoeffding finito: Δ̄ + R·√(ln(1/α_f)/(2N)) —
+    válido somente sob a suposição EXPLÍCITA R ≥ range verdadeiro
+    (o range observado NÃO serve: subestima o suporte e invalida a
+    cota — Teo 29.5-iii)."""
+    n = len(deltas)
+    if n == 0:
+        return float("inf")
+    media = float(np.mean(deltas))
+    if raio_declarado is not None and raio_declarado > 0:
+        t = float(raio_declarado) * np.sqrt(np.log(1.0 / max(alpha_f, 1e-12))
+                                            / (2.0 * n))
+        return media + t
+    from scipy import stats
+    s = float(np.std(deltas, ddof=1)) if n >= 2 else 0.0
+    tcrit = float(stats.t.ppf(1.0 - alpha_f, df=n - 1)) if n >= 2 else 0.0
+    return media + tcrit * s / np.sqrt(n)
+
+
+def avaliar_ganho(
+    x: np.ndarray, x_hat_antes: np.ndarray, x_hat_depois: np.ndarray,
+    z_antes: np.ndarray, z_depois: np.ndarray,
+    cfg: QECTConfig,
+) -> ResultadoQECT:
+    """Avalia se houve ganho real segundo QE + CT com NÍVEL α (Teo 29.5).
+
+    ganho_real ⟺ UCB_{1−α/2}(Δ_QE) < 0 E UCB_{1−α/2}(Δ_CT) < 0 E n ≥ n_min
+    (conjunção com erro de família ≤ α pela União de Bonferroni — cada
+    delta testa no nível α/2)."""
+    norm = bool(getattr(cfg, "normalizar", False))
+    qe_a = erro_quantizacao(x, x_hat_antes, normalizar=norm)
+    qe_d = erro_quantizacao(x, x_hat_depois, normalizar=norm)
+    ct_a = consistencia_temporal(z_antes)
+    ct_d = consistencia_temporal(z_depois)
+
+    d_qe = qe_d - qe_a
+    d_ct = ct_d - ct_a
+
+    # amostras por passo: QE sobre N pontos; CT sobre (T−1) transições —
+    # o teste usa o MENOR n (honesto: o elo fraco comanda o nível)
+    n_qe = x.shape[0]
+    n_ct = max(z_antes.shape[0] - 1, 1)
+    n = min(n_qe, n_ct)
+
+    alpha_f = float(getattr(cfg, "alpha", 0.05)) / 2.0
+    # reconstrói as séries de deltas por amostra p/ Hoeffding:
+    # QE: erro quadrático por ponto; CT: deriva por transição.
+    e_qe_a = np.sum((x - x_hat_antes) ** 2, axis=-1)
+    e_qe_d = np.sum((x - x_hat_depois) ** 2, axis=-1)
+    if norm:
+        e_qe_a = e_qe_a / (np.sum(x ** 2, axis=-1).mean() + 1e-12)
+        e_qe_d = e_qe_d / (np.sum(x ** 2, axis=-1).mean() + 1e-12)
+    deltas_qe = e_qe_d - e_qe_a
+    dr_a = np.sum((z_antes[1:] - z_antes[:-1]) ** 2, axis=(-1, -2))
+    dr_d = np.sum((z_depois[1:] - z_depois[:-1]) ** 2, axis=(-1, -2))
+    T = z_antes.shape[0]
+    w = np.ones(T) / T
+    deltas_ct = w[1:] * (dr_d - dr_a)
+
+    ucb_qe = _ucb_media(deltas_qe, alpha_f)
+    ucb_ct = _ucb_media(deltas_ct, alpha_f)
+    n_min = int(getattr(cfg, "n_min", 32))
+    significativo = (ucb_qe < 0.0) and (ucb_ct < 0.0) and (n >= n_min)
+
+    # compatibilidade: limiares fixos continuam como condição NECESSÁRIA
+    # (não suficiente) — mantém a semântica do rascunho nos casos claros
+    ganho = significativo and (d_qe < -cfg.eps_qe) and (d_ct < -cfg.eps_ct)
+    return ResultadoQECT(qe_d, ct_d, bool(ganho), d_qe, d_ct,
+                         ucb_qe=ucb_qe, ucb_ct=ucb_ct,
+                         significativo=bool(significativo), n_amostras=int(n))
+
+
+def te_antigo(x: np.ndarray, x_hat: np.ndarray, grid: np.ndarray) -> float:
+    """TE legado — distância média ao centro de grade mais próximo.
+
+    v17 (Teo 29.6): consulta via cKDTree — O((G+N)·log G) em vez de
+    O(N·G). Para centro mínimo único, devolve o MESMO valor do argmin
+    exaustivo (verificado bit-a-bit na suíte v17); empates exatos têm
+    medida zero sob grades contínuas e o tie-break do KDTree é
+    documentado (menor índice não garantido — diferença só em empate)."""
+    from scipy.spatial import cKDTree
+    arvore = cKDTree(grid)
+    d, _ = arvore.query(x, k=1)
+    return float(np.mean(d))

src/khtst/aprimoramento/tradeoff_k.py

@@ -0,0 +1,262 @@
+# -*- coding: utf-8 -*-
+"""Trade-off de K — v17 refatorada (doc 29 §6).
+
+Métodos: RD (J1), assintótico (J2) e grade (auditoria).
+
+NOVOS TEOREMAS desta revisão (provas completas no doc 29):
+
+Teo 29.9-i (UNIMODALIDADE — garante que minimize_scalar bounded acha o
+    mínimo GLOBAL). Com ε²(K) = C·K^{−2/d} (Zador) e
+        J1(K) = (1−λ)·C·K^{−2/d} + λ·(log₂K + K·d/n)/log₂d,
+    a derivada é
+        J1'(K) = −(1−λ)C·p·K^{−p−1} + λ·(K^{−1}/ln2 + d/n)/log₂d,  p = 2/d.
+    Multiplicando por K^{p+1} > 0:
+        G(K) = −(1−λ)C·p + λ·(K^p/ln2 + K^{p+1}·d/n)/log₂d.
+    G é ESTRITAMENTE CRESCENTE em K (K^p e K^{p+1} o são, coeficientes
+    > 0) ⟹ G tem no máximo uma raiz ⟹ J1' muda de sinal no máximo uma
+    vez. Como J1'(K) → −∞ quando K→0⁺ (K^{−p−1} domina K^{−1} pois
+    p+1 > 1) e J1'(K) → λ·d/(n·log₂d) ≥ 0 quando K→∞, J1 decresce e
+    depois cresce — MÍNIMO GLOBAL ÚNICO. Nenhuma aproximação.
+
+Teo 29.9-ii (FORMA FECHADA no regime n→∞): G(K)=0 dá
+        K* = [ (1−λ)·2·C·ln d / (λ·d) ]^{d/2}
+    (usando ln2·log₂d = ln d). Usada como INITIALIZATION/bracket do
+    minimizador numérico e como sanity check (o teste v17 compara a
+    forma fechada com a raiz numérica — coincidência a 1e-6 relativo).
+
+Teo 29.9-iii (SENSIBILIDADE — honestidade): da forma fechada,
+    ∂ln K*/∂ln C = d/2 — para d grande, K* é MUITO sensível a C. Por
+    isso Ĉ é estimado com SHRINKAGE ao prior: Ĉ = (n_C·Ĉ_ols + κ·C₀)/
+    (n_C + κ) — troca viés por variância com peso explícito (James–
+    Stein simplificado; o κ do config expõe o trade-off).
+
+D8 (C=1 FIXO — defeito do rascunho): a constante de Zador depende da
+    DISTRIBUIÇÃO (segundo momento normalizado da célula de Voronoi —
+    nunca é 1 em dados reais). Correção (Teo 29.8): medir ε²(K) na
+    grade e ajustar OLS em log-log: ln ε² = ln C − (2/d)·ln K + r;
+    consistência por LLN (r média-zero i.i.d. ⟹ (Ĉ, p̂) → (C, 2/d));
+    a INCLINAÇÃO ESTIMADA p̂ serve de TESTE DO MODELO: |p̂ + 2/d| grande
+    ⟹ o modelo de Zador não vale para esses dados ⟹ cai para a grade
+    (honestidade metodológica, registrada na telemetria).
+
+D9 (λ_c ESTÁTICO): o rascunho lia λ do config e nunca o atualizava;
+    agora `resolver_K` aceita λ_c adaptativo (saída do
+    AutoAjusteLambdaC — integração λ_c ↔ K* pela mesma unidade de
+    trade-off distorção×custo).
+"""
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from typing import Dict, Tuple
+
+import numpy as np
+from scipy.optimize import minimize_scalar
+
+from .config import TradeoffKConfig
+
+
+# ------------------ modelo de erro de quantização (Zador) ------------------
+
+def epsilon_sq(K, d: int, C: float = 1.0):
+    """Erro de quantização empírico ~ C·K^{−2/d} (Zador, alta resolução).
+
+    Domínio: K ≥ 1 (o modelo não é definido abaixo do codebook unitário;
+    K<1 é clampeado — elimina NaN de potências fracionárias negativas)."""
+    K = np.asarray(K, dtype=float)
+    return C * np.maximum(K, 1.0) ** (-2.0 / d)
+
+
+def estimar_C(K_medidos, e2_medidos, d: int, C_prior: float = 1.0,
+              kappa: int = 8) -> dict:
+    """Teo 29.8 — Ĉ por OLS log-log + teste do modelo + shrinkage.
+
+    Regressão: y_i = ln e2_i, x_i = ln K_i ⟹ y = a − p·x com a = ln C.
+    Ĉ_ols = exp(â); p̂ é a inclinação — se o modelo vale, p̂ ≈ 2/d.
+    Shrinkage: Ĉ = (n_C·Ĉ_ols + κ·C₀)/(n_C + κ)."""
+    K = np.asarray(K_medidos, dtype=float)
+    e2 = np.asarray(e2_medidos, dtype=float)
+    ok = (K > 0) & (e2 > 0)
+    K, e2 = K[ok], e2[ok]
+    n_c = int(K.size)
+    if n_c < 2:
+        return {"C": float(C_prior), "incl": float("nan"),
+                "modelo_ok": False, "n": n_c}
+    x, y = np.log(K), np.log(e2)
+    # OLS fechado (1D): y = a + b·x com b = incl ⟹ a = ȳ − b·x̄
+    # (C = exp(a); inclinação b ≈ −2/d se o modelo de Zador vale)
+    xm, ym = x.mean(), y.mean()
+    denom = float(((x - xm) ** 2).sum()) + 1e-12
+    incl = float(((x - xm) * (y - ym)).sum() / denom)
+    a = float(ym - incl * xm)               # intercepto correto (y = a + b·x)
+    c_ols = math.exp(a)
+    modelo_ok = abs(incl + 2.0 / d) <= max(0.35, 0.5 * (2.0 / d))
+    c_shrunk = (n_c * c_ols + kappa * float(C_prior)) / (n_c + kappa)
+    return {"C": float(c_shrunk), "C_ols": float(c_ols),
+            "incl": incl, "modelo_ok": bool(modelo_ok), "n": n_c}
+
+
+# --------------------------------- métodos ---------------------------------
+
+def J1(K: float, d: int, n: int, lam: float, C: float = 1.0,
+       bits_por_param: float = 16.0) -> float:
+    """J1 = (1−λ)·ε²(K) + λ·(log₂K + K·d/n)/log₂d — com C estimado (D8)."""
+    eps = float(epsilon_sq(K, d, C))
+    bits = (np.log2(max(K, 2)) + K * d / n
+            * (bits_por_param / 16.0)) / np.log2(max(d, 2))
+    return (1 - lam) * eps + lam * bits
+
+
+def J2(K: float, d: int, lam: float, C: float = 1.0) -> float:
+    eps = float(epsilon_sq(K, d, C))
+    return eps + lam * K / np.sqrt(d)
+
+
+def k_star_fechado(d: int, lam: float, C: float = 1.0) -> float:
+    """Teo 29.9-ii — K* = [(1−λ)·2·C·ln d/(λ·d)]^{d/2} (regime n→∞)."""
+    if not (0.0 < lam < 1.0) or C <= 0 or d < 2:
+        return float("nan")
+    return ((1.0 - lam) * 2.0 * C * math.log(d) / (lam * d)) ** (d / 2.0)
+
+
+def K_star_rd(cfg: TradeoffKConfig, C: float | None = None) -> float:
+    """Mínimo GLOBAL de J1 por minimize_scalar bounded (Teo 29.9-i garante
+    que o mínimo local é o global). Bracket centrado na forma fechada
+    quando disponível (Teo 29.9-ii) — acelera e ancora a busca."""
+    C = C if C is not None else 1.0
+    k_hint = k_star_fechado(cfg.d, cfg.lambda_c, C)
+    lo, hi = 4.0, 4096.0
+    if math.isfinite(k_hint) and k_hint > 0:
+        lo = max(4.0, k_hint / 8.0)
+        hi = min(4096.0, max(k_hint * 8.0, 32.0))
+        if lo >= hi:
+            lo, hi = 4.0, 4096.0
+    res = minimize_scalar(
+        lambda k: J1(k, cfg.d, cfg.n, cfg.lambda_c, C, cfg.bits_por_param),
+        bounds=(lo, hi), method="bounded",
+    )
+    return float(res.x)
+
+
+def K_star_asymp(cfg: TradeoffKConfig, C: float | None = None) -> float:
+    C = C if C is not None else 1.0
+    res = minimize_scalar(
+        lambda k: J2(k, cfg.d, cfg.lambda_c, C),
+        bounds=(4, 4096), method="bounded",
+    )
+    return float(res.x)
+
+
+def K_star_grid(cfg: TradeoffKConfig, C: float | None = None) -> float:
+    vals = [(k, J1(k, cfg.d, cfg.n, cfg.lambda_c, C, cfg.bits_por_param))
+            for k in cfg.K_grid]
+    return float(min(vals, key=lambda t: t[1])[0])
+
+
+# ----------------------------- orquestrador --------------------------------
+
+@dataclass
+class ResultadoK:
+    K_rd: float
+    K_asymp: float
+    K_grid: float
+    divergencia: float
+    metodo_escolhido: str
+    K_final: float
+    tabela: Dict[str, float]
+    # v17 — telemetria da estimação de C (D8) e do modelo de Zador
+    C_estimado: float = 1.0
+    C_ols: float = 1.0
+    inclinacao: float = float("nan")
+    modelo_ok: bool = False
+    K_fechado: float = float("nan")
+
+
+def medir_epsilon_sq(dados: np.ndarray, K_medidos, seed: int = 0) -> Tuple[np.ndarray, np.ndarray]:
+    """Mede ε²(K) REAL por quantização por k-means leve (Teo 29.8).
+
+    Usado quando `estimar_C=True` e dados estão disponíveis; sem dados,
+    o chamador pode passar pares (K, ε²) medidos por outra via (ex.:
+    espectro PCA via Eckart–Young — patches/correcoes.py)."""
+    Ks = np.asarray(list(K_medidos), dtype=int)
+    e2 = []
+    rng = np.random.default_rng(seed)
+    amostra = dados[np.random.default_rng(seed).choice(
+        dados.shape[0], size=min(4096, dados.shape[0]), replace=False)]
+    for k in Ks:
+        # k-means 1 inicialização + 8 iterações de Lloyd (leve, auditável)
+        centros = amostra[rng.choice(amostra.shape[0], size=k, replace=False)]
+        for _ in range(8):
+            d2 = ((amostra[:, None, :] - centros[None, :, :]) ** 2).sum(-1)
+            lab = d2.argmin(1)
+            for j in range(k):
+                pts = amostra[lab == j]
+                if len(pts):
+                    centros[j] = pts.mean(0)
+        d2 = ((amostra[:, None, :] - centros[None, :, :]) ** 2).sum(-1)
+        e2.append(float(d2.min(1).mean()))
+    return Ks.astype(float), np.asarray(e2)
+
+
+def resolver_K(cfg: TradeoffKConfig,
+               pares_medidos: Tuple[np.ndarray, np.ndarray] | None = None,
+               lambda_c_adaptativo: float | None = None) -> ResultadoK:
+    """Resolve K* com Ĉ estimado (D8) e λ_c adaptativo (D9).
+
+    pares_medidos: (K, ε²) medidos — alimenta o OLS de Ĉ. Sem eles e com
+    estimar_C=True, usa o prior (honesto: registra modelo_ok=False)."""
+    lam = float(lambda_c_adaptativo) if lambda_c_adaptativo is not None \
+        else float(cfg.lambda_c)
+    C_hat, C_ols, incl, modelo_ok = 1.0, 1.0, float("nan"), False
+    if cfg.estimar_C and pares_medidos is not None:
+        est = estimar_C(pares_medidos[0], pares_medidos[1], cfg.d,
+                        cfg.C_prior, cfg.kappa_prior)
+        C_hat, C_ols, incl = est["C"], est["C_ols"], est["incl"]
+        modelo_ok = est["modelo_ok"]
+
+    cfg_lam = TradeoffKConfig(
+        d=cfg.d, n=cfg.n, lambda_c=lam, K_grid=cfg.K_grid,
+        tol_rel=cfg.tol_rel, metodo=cfg.metodo,
+        estimar_C=cfg.estimar_C, C_prior=cfg.C_prior,
+        kappa_prior=cfg.kappa_prior, bits_por_param=cfg.bits_por_param)
+
+    k_rd = K_star_rd(cfg_lam, C_hat)
+    k_as = K_star_asymp(cfg_lam, C_hat)
+    k_gr = K_star_grid(cfg_lam, C_hat)
+
+    div = abs(k_rd - k_as) / max(k_rd, 1e-9)
+
+    if cfg.metodo == "auto":
+        # Teo 29.8 (honestidade): modelo de Zador ruim ⟹ confia na grade
+        if (not modelo_ok) and pares_medidos is not None:
+            escolhido, k_final = "grid", k_gr
+        elif div < cfg.tol_rel:
+            escolhido, k_final = "rd", k_rd
+        else:
+            escolhido, k_final = "grid", k_gr
+    else:
+        escolhido = cfg.metodo
+        k_final = {"rd": k_rd, "asymp": k_as, "grid": k_gr}[cfg.metodo]
+
+    return ResultadoK(
+        K_rd=k_rd, K_asymp=k_as, K_grid=k_gr,
+        divergencia=div, metodo_escolhido=escolhido,
+        K_final=k_final,
+        tabela={str(k): J1(k, cfg.d, cfg.n, lam, C_hat, cfg.bits_por_param)
+                for k in cfg.K_grid},
+        C_estimado=float(C_hat), C_ols=float(C_ols),
+        inclinacao=float(incl), modelo_ok=bool(modelo_ok),
+        K_fechado=float(k_star_fechado(cfg.d, lam, C_hat)))
+
+
+def validar_v15_1() -> Dict[int, Tuple[float, float]]:
+    """Compara K* bugado (b(K)=log₂K/log₂d) com K* corrigido (rate-distortion)."""
+    out = {}
+    for d in (64, 512, 4096):
+        def J_bug(k, d=d):
+            return float(epsilon_sq(k, d)) + 0.5 * np.log2(max(k, 2)) / np.log2(d)
+        r_bug = minimize_scalar(J_bug, bounds=(4, 512), method="bounded")
+        cfg = TradeoffKConfig(d=d, n=100_000, lambda_c=0.5)
+        r_fix = K_star_rd(cfg)
+        out[d] = (float(r_bug.x), float(r_fix))
+    return out

src/khtst/mamba3/hybrid.py

@@ -37,11 +37,11 @@ import torch.nn.functional as F
 from torch.utils.checkpoint import checkpoint
 
 from khtst.mamba3.kernel import varredura_trapezoidal
-from khtst.mamba3.replay import varredura_replay
 
 __all__ = ["NoPEAtencao", "Mamba3Camada", "HybridMamba3Modelo",
            "eh_camada_atencao", "EstadoMamba3"]
 
+
 class EstadoMamba3:
     """Estado recorrente de UMA Mamba3Camada para decode INCREMENTAL
     (v12, Teorema 24.13 — equivalência exata com a varredura paralela):
@@ -141,15 +141,11 @@ class Mamba3Camada(nn.Module):
     """Camada MAMBA-3 com gate SiLU + pré-norm + residual (doc 22 §3)."""
 
     def __init__(self, d_modelo: int, d_estado: int = 16, rank_mimo: int = 4,
-                 kernel_conv: int = 4, replay_segmento: int = 0):
+                 kernel_conv: int = 4):
         super().__init__()
         self.d = d_modelo
         self.n = d_estado
         self.r = rank_mimo
-        self.k_conv = kernel_conv
-        # v17 (doc 29, Teos 29.13–29.14) — ReplaySSM: nº de segmentos da
-        # varredura (0 = desligado ⟹ v12 exato, nascimento neutro)
-        self.replay_segmento = int(replay_segmento)
         self.entrada_proj = nn.Linear(d_modelo, 2 * d_modelo, bias=False)
         self.conv1d = nn.Conv1d(d_modelo, d_modelo, kernel_size=kernel_conv,
                                 padding=0, groups=d_modelo)  # causal manual
@@ -188,20 +184,7 @@ class Mamba3Camada(nn.Module):
             uc = F.pad(u.transpose(1, 2), (self.k_conv - 1, 0))
             uc = self.conv1d(uc).transpose(1, 2).contiguous()   # (B,L,D)
             delta, B_m, C_m = self._projetos(uc)
-            # v17 — ReplaySSM (Teos 29.13/29.14): varredura POR SEGMENTOS
-            # com replay de estados fronteira (gradiente e saída EXATOS;
-            # ativação O(S·BDN + L_s·BDN)). Só em treino com gradiente e
-            # L > 1 — decode incremental (T=1) nunca segmenta.
-            seg = int(getattr(self, "replay_segmento", 0) or 0)
-            if seg > 1 and self.training and torch.is_grad_enabled() and L > seg:
-                if devolve_estado:
-                    y, h_final = varredura_replay(uc, delta, self.A, B_m, C_m,
-                                                  n_segmentos=seg,
-                                                  devolve_estado=True)
-                else:
-                    y = varredura_replay(uc, delta, self.A, B_m, C_m,
-                                         n_segmentos=seg)
-            elif devolve_estado:
+            if devolve_estado:
                 y, h_final = varredura_trapezoidal(uc, delta, self.A, B_m,
                                                    C_m, devolve_estado=True)
             else:
@@ -254,7 +237,7 @@ class HybridMamba3Modelo(nn.Module):
 
     def __init__(self, d_modelo: int, n_camadas: int = 6, n_cabecas: int = 4,
                  d_estado: int = 16, rank_mimo: int = 4,
-                 grad_checkpointing: bool = True, replay_segmento: int = 0):
+                 grad_checkpointing: bool = True):
         super().__init__()
         self.d = d_modelo
         self.n_camadas = n_camadas
@@ -265,8 +248,7 @@ class HybridMamba3Modelo(nn.Module):
                 self.camadas.append(NoPEAtencao(d_modelo, n_cabecas))
             else:
                 self.camadas.append(
-                    Mamba3Camada(d_modelo, d_estado, rank_mimo,
-                                 replay_segmento=replay_segmento))
+                    Mamba3Camada(d_modelo, d_estado, rank_mimo))
         self.norm_f = nn.RMSNorm(d_modelo)
 
     def _corre(self, x: torch.Tensor, tarefa=None) -> torch.Tensor: