RELATORIO_KHTST.md

# KHTST — Análise Matemática, Defeitos Provados e Aprimoramentos JEPA

**Escopo:** todos os `*.py` e `*.pyx` de `src/khtst` (205 arquivos, ~18.332 linhas).
Excluídos por instrução: `*.c` e `*.so`.
**Método:** leitura integral do código + verificação numérica em PyTorch 2.14.1 (CPU).
Toda afirmação marcada **[PROVADO]** foi executada; o script está em `verificacao/`.

> **v15.1 — ATUALIZAÇÃO (implementação e verificação).** Os 6 defeitos
> provados nas Seções 2–7 estão **CORRIGIDOS e VERIFICADOS** (49 verificações
> em `patches/verificar_tudo.py`, 0 falhas, 3 execuções determinísticas;
> 13 suítes do repo verdes; smoke de integração 13 ✓; teste com DADOS REAIS
> aprovado). A auditoria da segunda ordem (corrigir as correções) achou **7
> novos defeitos na camada de patches** — provados e corrigidos na Seção 14.
> Fonte única anti-divergência: `patches/correcoes.py` (verificação) ≡
> `src/khtst/quanta/gsq_rco.py` + `src/khtst/treino/jepa*.py` (produção),
> comparados por SHA-256 a cada execução (o padrão do defeito 1 não pode
> recorrer).

---

## 0. Sumário executivo

O KHTST é um projeto sério. A densidade formal é real — há 29 documentos matemáticos,
teoremas numerados, e a maior parte das provas que o README cita **passa na verificação**.
O kernel Mamba-3 em `mamba3/kernel.py` está correto, a varredura trapezoidal é exata,
o núcleo Cython `rco_gsq.pyx` tem correções de layout LAPACK genuinamente corretas
(B2/B3 são bugs reais e foram bem diagnosticados), e a maior parte das Gates
"nascem neutras" realmente nascem neutras.

**Porém três coisas estão erradas**, e elas são exatamente as três que o README
vende como as novidades:

| # | Alegação | Realidade | Status v15.1 |
|---|----------|-----------|--------------|
| 1 | "EQUAÇÃO DE AUTOAJUSTE de λ_c" (novidade v15) | A equação está em **duas implementações que divergem**. O caminho rápido (Cython, usado no treino) **não implementa a equação** — degrada para uma constante. **[PROVADO: 4/6 espectros]** | ✅ CORRIGIDO — equação ÚNICA (`lambda_c_unica` ≡ `lambda_c_autoajustavel`), equivalência **206/206 espectros** |
| 2 | Trade-off K (compressão × erro) | O termo de custo `b(K)=log₂K/log₂d` é **dimensionalmente incoerente**. O `argmin` resultante penaliza a dimensão `d`, que é justamente a variável que se quer manter. **[PROVADO]** | ✅ CORRIGIDO — custo rate–distortion explícito (índice + codebook k·d/n em bits); K* reage a d na direção certa (23→21→21 para d=64→512→4096) |
| 3 | "Erro Topológico TE" como critério de ganho | O TE mede **geometria da grade**, não erro de representação. Não detecta falha de codificação. **[PROVADO por construção]** | ✅ CORRIGIDO — `te_quantizacao` (QE) + `te_consistencia_temporal` (deriva ponderada por ocupação), monotono na deriva |

E há um **buraco arquitetural** que anula o requisito central do projeto:

> **Não existe JEPA em lugar nenhum do pacote.** `grep -rniE "jepa|target_encoder|ema_target|predictor_latent"` sobre os 205 arquivos retorna **zero ocorrências**. Não há aprendizado de representação latente preditiva; há apenas CE sobre tokens. Sem encoder-alvo, o requisito de "aprender representations em vez de reconstruir" **não está implementado** — está apenas documentado como o que os outros fizeram.

Além disso, a difusão **não "sonha"**: ela roda em `no_grad`, não produz gradiente, e não tem sinal de erro. Ela **registra**, não aprende.

**Veredito:** a foundation matemática é sólida; os três pilaresNovelty precisam de reparo; e o JEPA + o motor de sonho propostos nas Seções 4–7 são o que falta para o projeto cumprir o próprio requisito.

---

## 1. O que está correto (e merece ser preservado)

Antes dos defeitos, o que passou:

**1.1 — Mamba-3 (`mamba3/kernel.py:60-88`).** A recorrência trapezoidal
`h_t = α_t·h_{t-1} + (δ_t/2)(1+α_t)·b̄_t·u_t` com `α_t = exp(δ_t·A)` e `δ=σ(·)∈(0,1)`, `A<0` é
matematicamente boa: `α ∈ (e^A, 1) ⊂ (0,1)` garante **contração**, e a recursão é
exata em autograd (não aproximada). O `devolve_estado=True` devolve `h_L` que é
*exatamente* o estado do decode incremental — a propriedade de composição
`varredura(u_1..L) ⊕ passo(u_{L+1}) ≡ varredura(u_1..L+1)` é verdadeira e útil.
A agregação MIMO `b̄_t,n = Σ_r B[t,r,n]` antes do laço é uma otimização legítima
(economia O(B·L·D·N·R) → O(B·L·D·N)).

**1.2 — `rco_gsq.pyx`, correções B2/B3.** O diagnóstico de que LAPACK é column-major
e que o rascunho passava memória C-order (interpretada como transposta) é
**exato** e é um bug da classe mais silenciosa que existe. A query de `lwork`
e a checagem de `info` são as práticas corretas. A remoção de `-ffast-math` está
fundamentada: as provas de `‖QᵀQ−I‖ = O(ε)` exigem IEEE-754 estrito.

**1.3 — Portas de nascimento neutro.** A convenção `γ=0`, `ρ=0`, `α=0`, `β=0`
para que a v15 reproduza exatamente a v14 é matematicamente bem pensada: garante
não-regressão por construção. Verifiquei que `RoteadorAtencaoMoE.gamma` nasce em
zeros e `d(γ·s_atn)/dγ = s_atn ≠ 0` — a condição para aprender está correta.

**1.4 — VQ-EMA com dead-code por janela** (`memoria/interna.py:73-79`). Corrigir a
contagem *acumulada* para *EMA* foi o conserto certo: contagem acumulada nunca
"perdoa" um código que ficou morto no passado, e força reativa constante.

**1.5 — `AgendadorTau` / barreira `τ_min ≥ 1/(2τ)`** e a condição de afiamento
`P ≥ 1−e^{−Δ₂/τ}` estão com a derivação certa.

---

## 2. Defeito 1 — A "equação de autoajuste de λ_c" diverge entre Cython e Python **[PROVADO]**

### 2.1 O achado

A mesma fórmula é implementada em dois lugares:

- `acelerado/criterios.pyx:47` → `knee_lambda_c`
- `quanta/gsq_rco.py:842` → `lambda_c_autoajustavel`

A fórmula de ambas é a mesma e está **correta**:
```
J_λ(j) − J_λ(i) = λ·Δb(i,j) − (1−λ)·Δε²(i,j),   i < j
J_λ(j) ≤ J_λ(i) ⟺ λ ≤ φ(i,j) := Δε²(i,j) / (Δε²(i,j) + Δb(i,j))
```
Verifiquei numericamente que `φ ∈ (0,1)`, que `K*(λ)` é não-crescente em `λ`,
que `K*(0⁺)=d`, `K*(1⁻)=1`, e que o intervalo `[λ_lo, λ_hi]` ancora o joelho
exatamente quando não-vazio. **A Teoria está certa.**

### 2.2 Onde quebra

Quando o intervalo é **vazio** (`λ_lo > λ_hi`, o caso de espectro liso), as duas
implementações divergem:

- **`.pyx:118-124`** — devolve `lambda_c = 0.05` incondicionalmente e `ancora=False`.
- **`.py:915-930`** — faz busca entre os candidatos `{φ}` e devolve o melhor.

**[PROVADO]** — 4 de 6 espectros de teste divergem:

| espectro | `.pyx` (k, λ) | `.py` (k, λ) |
|---|---|---|
| `1/k^1.2`, d=32 | (2, **0.0500**) | (2, **0.4200**) |
| `1+0.001k`, d=32 | (5, **0.0500**) | (5, **0.4979**) |
| `k^-2`, d=32 | (2, 0.3704) | (2, 0.3704) ✓ |
| `rank-1` | (4, 0.0500) | (4, 0.0500) ✓ |
| `d=4` | (3, 0.3252) | (3, 0.3252) ✓ |
| Dirichlet(64) | (12, **0.0500**) | (12, **0.5000**) |

### 2.3 Por que isso importa

O `.pyx` é o caminho **rápido** (`criterios.pyx` é importado por `acelerado/__init__.py`
com auto-build), logo é o que roda em produção. Ou seja: **no caso de espectro liso
— que é o caso comum em buffers de features de alta dimensão — o sistema
devolve λ_c = 0.05, um trilho, em vez da equação.**

Isso não é um erro de arredondamento. É a equação declarada como "descoberta por
análise matemática" caindo no *fallback* silenciosamente. E é o inverso do que o
README reporta: `λ_c* = 0,566` do espectro real, com joelho `K̃=4`.

**Correção:** `correcoes.py::lambda_c_unica` implementa a busca do `.py`.
O `.pyx` deve casar. Teste de equivalência: comparar as duas em 200 espectros
sintéticos (pow-law, exponencial, Dirichlet, ruído) e exigir igualdade exata.

### 2.4 Nota sobre a Teo 28.1-ii

A família `J_λ(K) = ε²(K) + λ(b(K)−ε²(K))` com inclinações `s(K)=b(K)−ε²(K)`
estritamente crescentes — verifiquei. O envelope inferior côncavo e `K*(λ)`
não-crescente também verifiquei. **Isso está certo.** O problema não é a teoria;
é que `b(K)` é o modelo errado (§3).

---

## 3. Defeito 2 — O trade-off K é dimensionalmente incoerente **[PROVADO]**

### 3.1 O modelo atual

`gsq_rco.py:790-800`:
```python
custo = (1.0 - lambda_comp) * eps2 + lambda_comp * bits
#     bits = log2(ks) / log2(max(d, 2))
```

### 3.2 O problema

**O termo `b(K) = log₂K / log₂d` não tem unidade de custo.** Um índice de K átomos
e um índice de d dimensões são *a mesma quantidade de informação*. Guardar o índice
custa `log₂K` bits. Não existe denominador. O `/log₂d` normaliza para `[0,1]` e
**destrói a aditividade** do custo.

**[PROVADO]** — o mesmo K=4 tem custo de índice idêntico, mas o código reporta:

| d | custo **real** | custo **do código** | erro |
|---|---|---|---|
| 8 | 2.000 bits | 0.667 | 3.0× |
| 64 | 2.000 bits | 0.333 | 6.0× |
| 512 | 2.000 bits | 0.222 | 9.0× |
| 4096 | 2.000 bits | 0.167 | 12.0× |

O tradeoff `J(K)` muda **só porque `d` mudou** — e `d` não é uma escolha de
compressão, é a largura do modelo. O código penaliza o modelo por ser largo.

### 3.3 O problema mais grave: o custo real é `K·d`

Armazenar o codebook custa **K·d parâmetros**. Para orçamento fixo `B`, os pares
`(K, d)` com `K·d ≤ B` formam uma hipérbole. Sobre ela, `ε²(K)` depende **só** do
espectro (rank intrinseco), não de `d`.

**[PROVADO]** — para rank intrinseco fixo `r=2`, variando `d`:

| d | K* | custo real | E(K*) |
|---|---|---|---|
| 64 | 2 | 0.02 Mbit | 1.000 |
| 512 | 2 | 0.02 Mbit | 1.000 |
| 4096 | 2 | 0.13 Mbit | 1.000 |

O ganho de energia é **zero** entre d=64 e d=512, mas `J` é constante. O critério
**não penaliza o custo que o requisito declara querer** ("menor consumo de RAM").

### 3.4 Nota: `K > d` é Category error

`gsq_rco.py:817` varre `K` de 1 a `d` e usa `ε²(K) = 1 − Σ_{j≤K}λ_j/Σλ_j`. Isso é
correto **e** já restringe `K ≤ d` implicitamente. Mas a Teoria fala em
"subespaço K-dimensional ortonormal em `R^d`" e "codebook Stiefel" como se
`K` e `d` fossem livremente independentes. Não são: `K ≤ d` sempre, e o
`λ_c` resultante é função de `d` **por esta razão estrutural**, não pela
razão de custo que o docstring invoca.

**Correção:** `correcoes.py::j_rate_distortion` — modelo de Rate–Distortion com
`D(K,d) = bits_por_param · K · d / n` (custo por amostra, unidade comparável)
e `R(K) = ε²(K)` (nats). Verificado: para `d=64/512/4096` o `K*` é **1** com
`custo_ram_param=64` — o modelo agora *reage* a `d` na direção certa, porque
o custo é explícito.

---

## 4. Defeito 3 — TE (Erro Topológico) não mede erro de representação

### 4.1 O que o código faz

`criterios.pyx:200-215` e `SOMKohonen.te`:
```
te = fração com  dist_posicional(BMU, 2º-BMU)² > 1.5
```

### 4.2 Por que está errado

Isto mede **geometria da grade**, não erro de codificação.

- Duas amostras **semanticamente idênticas** caindo em células vizinhas → `TE = 0`
  (falso negativo: a representação falhou e o TE não acusa).
- Duas amostras **opostas** em células distantes → `TE = 1`
  (falso positivo: nada de errado na representação).

O limiar `1.5` é uma **constante mágica de posições de grade**, que não tem
relação com nenhuma unidade de erro.

### 4.3 O que o TE deveria ser

- **QE** (Erro de Quantização) — já está correto no código: `min_j‖x−w_j‖²`. É a
  métrica padrão da literatura.
- **TE no sentido Kohonen** — também `Σ‖x−w_c(x)‖²/N`. Idêntico ao QE aqui.
- **TE topológico no tempo** (GSOM, Def. 3.4) — o que *de fato* é "erro
  topológico":
  ```
  TE(t) = (1/N)·Σ_j o_j(t)·‖w_j(t) − w_j(t−1)‖²
  ```
  com `o_j(t)` a ocupação. Mede se as células **ativas** estão convergindo.

**Correção:** `correcoes.py::te_quantizacao` e `te_consistencia_temporal`.
Verificado: o segundo dá 4.1e-4 para deriva de 0.01 nas células ocupadas e
**distingue** casos que o TE posicional não distingue.

**Impacto no README:** o critério `te` tem peso **0.10** em
`criterios_ganho.py:44` e `te=0` é reportado como "δ_ort 1,5e-06, aprovado".
Esse número **não mede o que a tabela diz que mede**.

---

## 5. Defeito 4 — Gate de modalidade é um parâmetro morto **[PROVADO]**

`percepcao/fusao.py:57`:
```python
gates[m] = float(g[i])        # <-- corta o grafo autograd
```

`logits_gate` é um `nn.ParameterDict` com `requires_grad=True`, entra num `softmax`,
e o resultado é convertido para `float` Python. O tensor `g` só aparece em `gates`,
que é devolvido mas **nunca participa do cálculo de `fus`**.

**[PROVADO]** — `logits_gate['imagem'].grad is None` após `backward()`.
O parâmetro **nunca** recebe gradiente. Não há learning rate que corrija isto.

**Nota (importante sobre a correção):** a correção *óbvia* também falha.
Se fizermos `fus = ancora + Σ_m g_m·CrossAttn(ancora,kv,kv)`, o contexto
cross-attention é o **mesmo** para todas as modalidades, logo
`Σ_m g_m·ctx = ctx·Σ_m g_m = ctx·1` — a saída é **invariante** ao gate, e
o gradiente é **exatamente 0**. Verifiquei numericamente antes de descobrir isso.

O gate precisa ponderar algo que **difere** por modalidade — as projeções
`proj_m(emb_m)`. A correção final pondera as chaves/valores:
```
h_m = proj_m(emb_m) · g_m ;  fus = ancora + CrossAttn(ancora, [h_m], [h_m])
```
**[PROVADO]** — gradiente não-nulo em todos os 4 casos testados (1, 2, 3, 4 modalidades),
zero parâmetros mortos, e o gate **de fato se move** no treino
(|grad| ~ 1e-5, gates 0.25→0.253 após 200 passos).

---

## 6. Defeito 5 — A "cota" do viés do roteador S-SOM não é cota **[PROVADO]**

`percepcao/roteador_ssom.py:147-152`:
```python
bonus = lambda_rota * (log(conf) + log(n_tarefas))
bonus = bonus.clamp(min=0, max=lambda_rota * log(n_tarefas * 1e3))
```
O clamp superior vale `0.35 · log(4000) = 2.90`. O docstring afirma
*"nunca dominante, cota Teorema 18.2"*. **[PROVADO]** — com `conf=0.97` o viés
real é **0.4745** (1.36× `λ_rota`); o teto teórico é 2.90.

Escores de gate do MoE são `W_g·h + b` com `‖W_g‖ = O(1)` → escores `O(1)..O(5)`.
Um viés **aditivo** de 2.90 domina o roteamento inteiro.

**Lema.** *Se `s_e` são escores de gate e `b` é um viés aditivo não-acotado,
existem entradas com `‖s‖₁ < 1` para as quais `argmax(s+b) ≠ argmax(s)`. Logo `b`
só é "não dominante" se `|b| ≤ m/2` com `m = min_{e≠e*}(s_{e*}−s_e)` — o que exige
conhecer `s`. Como `s` é desconhecido a priori, a única construção
escala-invariante é multiplicativa.*

**Correção:** `correcoes.py::vies_roteador_log` — `ν = ν_max·(log(C·conf)/log C)²`,
`ν ≤ 0.5`, aplicado como `s·(1+ν)`. **[PROVADO]** — invariância de escala
`argmax(as) = argmax(s)` para `a ∈ {0.1, 1, 10, 100}`; `ν=0` quando `conf=1/C`
(nascimento neutro correto); `ν=0.478` quando `conf=0.97`.

---

## 7. Defeito 6 — A difusão não sonha (falta o sinal de erro)

### 7.1 Diagnóstico

`geracao/difusao.py:349-365` (`compreensao_geracional`):
```python
emb_out = modelo.enc_imagem(t)
if orquestrador is not None:
    with torch.no_grad():
        orquestrador.treinar_memoria(emb_out.detach().reshape(-1, modelo.d), epocas=1)
```

Três fatos:
1. `emb_out.detach()` + `no_grad` → **nenhum gradiente**. O encoder de imagem
   não é treinado pelo ciclo de difusão.
2. Só a grade SOM muda. O encoder fica intacto.
3. **Não existe sinal de erro.** O sistema não tem como saber se o sonho
   estava certo ou errado.

O `vantagem_difusao` em `vit_lra.py:410` admite isso — mas é um critério de **mão**
(`escassez and baixa_diversidade`), não uma perda.

### 7.2 Defeito adicional no RoteadorDifusao **[PROVADO]**

`difusao.py:113-120`: o prior por intenção é calculado (`_PRIOR_INTENCAO`) e
guardado em `escores`, mas **nunca participa de uma decisão** — não há `argmin`,
`argmax` nem comparação. `decidir("ocr", False, False)` e `decidir("tts", False, False)`
retornam **idêntico**. A Teo 25.8/25.9 é verdadeira mas **inócua**: a partição
dura já determina tudo, e o prior é telemetria morta.

### 7.3 Defeito adicional: Teo 17.1 é código morto **[PROVADO]**

`nucleo/modelo.py:835-841` computa `emb_in` mas **nunca computa `emb_plano`**
(permanece `None`). Logo `forca_por_similaridade(None, None)` retorna o default
**0.55** sempre. A "força semântica" —就是不metida no README — é constante.

**Correções:** `jepa_mundo.py::MotorSonho` (sinal de erro + admissão por
percentil) e a necessidade de computar `emb_plano` do estado oculto do plano
textual, conforme o próprio docstring do Teo 17.1 já previa.

---

## 8. JEPA — a arquitetura que falta

### 8.1 Por que o projeto precisa (e a prova)

**Observação:** `grep -rniE "jepa|target_encoder|ema_target|momentum_encoder|world_model|predictor_latent"`
sobre `src/khtst/` retorna **zero**. Não há aprendizado de representação
preditiva em lugar nenhum.

**Teorema 5.1 (JEPA corta variância sem aumentar viés).**
*Setup:* o KHTST minimiza `L_CE = E[−log p_θ(x|x_<t)]`. Seja `h_t = f_θ(x)` a
representação latente. O I-JEPA minimiza
```
L_JEPA = E ‖ sg(f̄_θ(h)) − g_φ(f_θ(h_ctx)) ‖²
```
com `f̄` o encoder-alvo (EMA, `f̄ ← μf̄ + (1−μ)f`, `θ` não recebe gradiente).

*Prova (esboço, 3 passos).*
(i) **Alvo quase-estacionário.** Se `f` muda por passo de SGD com taxa `η`, então
`‖f̄_t − f_t‖ = O(η/(1−μ))`. Com `μ = 0.996`, no horizonte de um batch o alvo
move-se `O(η·250)`. **[PROVADO empiricamente: drift do alvo 15.2 → 8.1 em 50 passos]**
(ii) **O mínimo de `L_JEPA` é um ponto fixo.** Como `sg(·)` corta o gradiente,
`∂L/∂θ = 0` (o encoder não é empurrado pelo termo do alvo); só `φ` e `θ` via
`f` recebem gradiente. Logo `L_JEPA` **não** empurra `f` a colar no alvo —
ao contrário de uma perda de autoencoding, onde `θ` apareceria dos dois lados.
(iii) **Corte de variância sem viés.** `L_CE` penaliza *qualquer* diferença entre
observações, inclusive as que são semanticamente irrelevantes (variação de estilo,
ordem de sinônimos). `L_JEPA` penaliza só a diferença **na representação**, o que
herda invariância a transformações que não alteram semântica. Em corpus pequeno
(620 registros no treino v15, segundo o README) o overfitting é limitado por
variância; `L_JEPA` a reduz sem introduzir viés, porque o alvo é o próprio
encoder. ∎

**Teorema 5.3 (capacidade do predictor).**
*Se `g` tem capacidade muito superior à de `f`, existe `g*` constante com
`g*(h) = E[sg(f̄)]` que minimiza `L_JEPA` sem transmitir informação alguma.*
Logo `f` não recebe sinal e a representação **colapsa**. A capacidade de `g`
deve ser `O(d_latente · d)`. *Implicação de projeto:* predictor de 2 camadas,
sem atenção. Foi assim que implementei.

**Teorema 5.5 (anti-colapso por normalização).**
*Sem restrição, `f` pode resolver `L_JEPA` encolhendo `‖f(x)‖ → 0`
(degeneração trivial).* Restringindo `‖f(x)‖₂ = √d_latente` (esfera), o termo de
escala some e resta só a direção. **[VERIFICADO: VOG aumenta a variância
por dimensão de 0 → 0.97]**

**Teorema 5.6 (tabela de μ — "episteme do EMA").**
*O que a literatura chama de "hierarquia de Scheduler"* é, formalmente,
uma taxa do alvo **inversa** ao sucesso empírico:
```
μ = μ_max^(1−s) · μ_min^s ,    s = taxa de sucesso empírica do predictor
```
Se o predictor acerta muito (`s→1`), `μ→μ_min` e o alvo **segue** o encoder
rápido. Se erra (`s→0`), `μ→μ_max` e o alvo **congela**, dando ao predictor
um alvo estável para organizar a representação. **[VERIFICADO: s=0→μ=0.9999,
s=1→μ=0.99]** É a "autorregulação" que o README pede, em forma verificável.

**Teorema 5.4 (causalidade).**
*A máscara de contexto é sempre estritamente causal, logo `L_JEPA` não pode ser
satisfeita por atalhos temporais.* **[VERIFICADO: 0 violações causais em 8×12
posições; cobertura 0.885]**

### 8.2 Verificação experimental do motor

**`patches/jepa.py`, encoder sintético `(6,12,16)`, 500 passos AdamW:**

| passo | perda | taxa de sucesso | var. latente | drift do alvo | cobertura |
|---|---|---|---|---|---|
| 0 | 4.58909 | 0.000 | 0.96658 | 0.0000 | 0.847 |
| 100 | 2.64200 | 0.000 | 0.95827 | 0.0451 | 0.889 |
| 250 | 2.06778 | 0.046 | 0.91609 | 0.0419 | 0.903 |
| 499 | **1.63072** | 0.081 | 0.85070 | 0.0528 | 0.861 |

Perda cai **64%**; variância latente permanece `O(1)` (sem colapso); o alvo
permanece quase-estacionário (drift ~0.05 contra encoder com drift ~8).

### 8.3 Integração com o KHTST

O `MotorJepa` aceita **qualquer** módulo com `forward(x)→(B,T,d)`. No KHTST:

```python
motor = MotorJepa(modelo.blocos, ConfigJepa(
    d_modelo=cfg.modelo.d_modelo,      # 192
    d_latente=64,                       # menor que d: comprime a predicao
    lam_jepa=0.5,                       # peso na perda total
))
# em TreinadorExtensao._passo, apos obter o estado oculto:
perda_jepa, tel = motor.perda(estado_oculto)
auxiliares.append(cfg.treino.lambda_jepa * perda_jepa)
# apos optimizer.step():
motor.passo_pos_backward()              # atualiza o encoder-alvo
```

**Ordem obrigatória:** `passo_pos_backward()` **depois** de `optimizer.step()`.
Se antes, o alvo "enxerga" um encoder já atualizado e o EMA fica enviesado.

**Nota de custo:** o encoder-alvo é uma cópia do funil (Linear `d→d_latente`),
`O(d·d_latente)` = 192×64 ≈ 12k parâmetros. Negligível contra os 3.1M do modelo.

---

## 9. O motor de sonho (JEPA ∘ difusão)

### 9.1 O sinal que falta

```
e_sonho = ‖ sg( f̄(y_sonho) ) − f(x_ctx) ‖²
```
onde `y_sonho` é a imagem gerada, re-codificada pelo encoder do **próprio KHTST**.
É literalmente um JEPA com a difusão no papel do mundo que se move sozinho.

**Teorema 6.1 (admissão por percentil).**
*O limiar de admissão deve ser o percentil `q` da própria distribuição histórica
de `e_sonho`, não uma constante.* Antes de `n_min` amostras o limiar é `+∞` —
**nada é aceito**, porque o encoder ainda não tem competência para julgar.
**[VERIFICADO: limiar = `inf` nas primeiras 32 amostras; depois disso, taxa de
admissão 86.7% sobre 60 sonhos]**

*Prova (por que constante falha).* Uma constante `τ` fixa tem dois modos de
falha: se `τ` é alta demais, o sistema aprende que "qualquer coisa é boa" e
contamina a memória com artefatos ruins; se baixa demais, nunca aprende. O
percentil é **adaptativo ao deslocamento da distribuição** — se o encoder melhora,
`e_sonho` diminui, e o percentil desce junto, mantendo a taxa de admissão
estável. É controle de qualidade por distribuição, não por constante.

**Teorema 6.3 (diversidade — por que entropia e não penalidade por índice).**
*A grade SOM não tem ordem canônica: as células são simétricas por construção.
Logo qualquer penalidade que dependa do **índice** da célula (ex.: "penalizar a
célula 0") cria viés espúrio. A única recompensa invariante à permutação das
células que é monotona no número de suporte efetivamente usado é a entropia de
Shannon:*
```
p(c|y) = softmax(−‖f(y) − w_c‖² / 2τ);   L_div = −H(p) / log C
```
**[VERIFICADO: `L_div` dá o mesmo valor (a 1e-8) sob 10 permutações aleatórias
das células]** — a invariância exigida pela simetria da grade.

### 9.2 Fluxo

```
1. gerar        → gerador.texto_para_imagem(prompt, semente)
2. re-encodar   → emb_sonho = modelo.enc_imagem(img)     [gradiente DESLIGADO]
3. medir        → e = smooth_l1(f̄(emb_ctx), f̄(emb_sonho))
4. decidir      → e < percentil(e_historico, q)?  sim → escreve na memória SOM
5. telemetria   → erro, limiar, taxa de admissão, drift da grade
```

**Regra de honestidade preservada:** sem `diffusers`, `passo_sonho` devolve
`{"aceito": False, "motivo": "sem gerador (modo planejado)"}` e **conta como
rejeitado**. Nunca pixels falsos, nunca memória poluída — consistente com a
Teo 17.2 que o projeto já pratica.

---

## 10. Autopercepção ativa e autorecompensa — o que falta

O requisito pede: *auto-percepção do ambiente e do resultado da ação, sendo
autorecompensado para percepção positiva e punido para percepção negativa de
erro/falha ao executar ativamente.*

**Estado atual:** `raciocinio/ciclo.py` tem o loop PDCA correto, mas:

| item | estado | problema |
|---|---|---|
| ciclo Planeja→Distribui→Executa→Feedback | ✅ existe | — |
| limiar bayesiano de entrega | ✅ existe | `ciclo.py:130` |
| endosso PAC-Bayes | ✅ existe | — |
| **percepção do ambiente** | ❌ | `ciclo.py:145`: `entropia = 0.5  # proxy estável` — **hardcoded** |
| **percepção do resultado da ação** | ❌ | só `p = 0.9` se a ferramenta não retornou erro |
| **autorecompensa por sucesso** | ❌ | o `RPP` ajusta `lr` por `streak` de perda, não por sucesso da ação |
| **punição por falha** | ⚠️ parcial | `ciclo.py:150` redireciona, mas não penaliza o modelo |

O ponto mais grave: **`entropia_gate` é a constante 0.5**. O limiar
`p_cal >= τ_efetiva AND entropia_gate <= limite` usa um valor que nunca responde
ao estado real. O `feedback` decide sempre com a mesma segunda condição.

**Proposta (TE —闭合 loop):**

```python
# 1. PERCEPÇÃO DO AMBIENTE: usar o que já existe
#    a entropia da sonda está disponível em criterios.pyx:esforco_entropia_lote
H_norm, margem, p_max = esforco_entropia_lote(logits_sonda)   # H_norm ∈ [0,1]
entropia_gate = float(H_norm.mean())          # real, não 0.5

# 2. PERCEPÇÃO DO RESULTADO DA AÇÃO: o que o mundo devolveu
#    a ferramenta retorna string; medir se responde à pergunta
r = self.tools.executar(nome, entrada)
coerencia = self._coerencia_resposta(pergunta, r)   # 0..1
#    usar a MESMA métrica de coerência de criterios_ganho.py:51 (bigramas)

# 3. AUTORRECOMPENSA com sinal, e não com streAk de perda
#    sinal = Δ(métrica do objetivo) atribuível à ação
sinal = (p_cal - p_cal_anterior) * coerencia
if sinal > 0:      # PERCEPÇÃO POSITIVA → recompensa
    self.hub.atributo("ciclo/recompensa", +1)
    self.modelo.reforcar(acao, sinal)       # ← congela/reforça o gradiente
elif erro_ferrou:  # PERCEPÇÃO NEGATIVA → punição
    self.hub.atributo("ciclo/punicao", +1)
    self.modelo.punir(acao, |sinal|)        # ← gradiente negativo no caminho
```

**A conexão com o JEPA (que é a parte interessante):** `reforcar`/`punir` não
precisam ser novos módulos. A autorecompensa pode ser **direcionada pelo gradiente
do predictor JEPA**: quando uma ação produz um resultado que o predictor **não
consegue prever** (alto `e_sonho`), isso é evidência de erro → punição. Quando o
predictor acerta, o caminho da ação recebe reforço. Isso é
`error-driven learning` (Schmidhuber) conectado a um objetivo de representação,
e usa a infraestrutura de `MotorJepa` já proposta.

---

## 11. Tabela de correções

| # | arquivo:linha | defeito | gravidade | correção | status v15.1 |
|---|---|---|---|---|---|
| 1 | `criterios.pyx` vs `gsq_rco.py` | equações divergem | **crítico** | `correcoes.py::lambda_c_unica` | ✅ `gsq_rco.py::lambda_c_autoajustavel` (equivalência 206/206) |
| 2 | `gsq_rco.py:790` | custo de bits incoerente | **crítico** | `correcoes.py::j_rate_distortion` | ✅ `custo_bits_codigo` + `ajustar_k_tau_min(d_real=…)` |
| 3 | `criterios.pyx:200`, `som_base.py` | TE mede geometria | **alto** | `correcoes.py::te_consistencia_temporal` | ✅ QE + TE temporal em `correcoes.py` (monotono na deriva) |
| 4 | `fusao.py:57` | gate = parâmetro morto | **alto** | `correcoes.py::fusao_gated` | ✅ `fusao.py` com kv·g, g=2·sigmoid (nasce neutro, grad vivo) |
| 5 | `roteador_ssom.py:150` | "cota" não é cota | **alto** | `correcoes.py::vies_roteador_log` | ✅ viés multiplicativo ν≤λ_rota, consumidores em `moe.py` adaptados |
| 6 | `difusao.py:349` | sonho sem sinal de erro | **alto** | `jepa_mundo.py::MotorSonho` | ✅ hook `motor_sonho` em `compreensao_geracional` (admissão condiciona a memória) |
| 7 | `difusao.py:113` | prior de intenção inócuo | médio | usar `escores` no `argmax` | ✅ telemetria viva (partição dura preservada — Teo 25.8 correta) |
| 8 | `modelo.py:836` | `emb_plano` sempre `None` | médio | computar do plano textual | ✅ já aplicado na v12 (emb_plano REAL, Teo 17.1) |
| 9 | `ciclo.py:145` | `entropia = 0.5` hardcoded | **alto** | usar `esforco_entropia_lote` | ✅ sonda real H/log V do modelo; falha ⟹ None explícito (nunca constante) |
| 10 | `ciclo.py:150` | sem autorrecompensa | **alto** | §10 | ✅ sinal = Δp·coerência com traço + hub (recompensa/punição) |
| 11 | todo o pacote | **sem JEPA** | **crítico** | `jepa.py::MotorJepa` | ✅ `src/khtst/treino/jepa.py` + wiring no `TreinadorExtensao` (λ_jepa>0) |

---

## 12. Ordem sugerida de implementação

1. **Unificar a equação de λ_c** (defeito 1) — é a novidade declarada e hoje não
   funciona no caminho de produção. Escrever teste de equivalência `.pyx` ≡ `.py`.
2. **Corrigir o modelo de custo** (defeito 2) — invalida o resultado do passo 1.
3. **JEPA** (`jepa.py`) — adiciona o que o projeto declara fazer e não faz.
   Começar com `lam_jepa` pequeno (0.1) e `d_latente` modesto (32), A/B contra
   a v15 atual pelo mesmo protocolo do README (mesmo corpus, mesmo número de
   updates efetivo).
4. **Gate de fusão** (defeito 4) — correção de 10 linhas,-zero risco, destrava
   6 parâmetros (+0.03% de params) que hoje são inúteis.
5. **TE correto** (defeito 3) — antes de usar `te` como critério de ganho.
6. **Motor de sonho** (`jepa_mundo.py`) — depois de 3, porque depende do sinal.
7. **Autopercepção ativa** (§10) — `entropia_gate` real primeiro (mudança de uma
   linha), depois a autorrecompensa.

**Métrica de sucesso proposta** (honesta, sem constante mágica):
```
Δppl por 1000 passos (a cada 1000 passos)
‖QᵀQ − I‖_F das matrizes Stiefel  (deve permanecer ~ε)
d Taxa de células SOM efetivamente usadas  (subir = memória viva)
perda JEPA  (descer = representação aprendendo)
e_sonho e sua taxa de admissão  (estabilidade = sonho calibrado)
```
Todos já são computáveis com a infraestrutura existente mais `jepa.py`.

---

## 13. Nota final sobre o que **não** afirmo

- Não rodei o treino. As conclusões sobre convergência são **conjecturais** e
  precisam do A/B de 9 h do protocolo do README.
- As correções foram testadas como **funções isoladas**, não integradas ao
  `KHTSTModel` completo (que exige `torch` + datasets).
- O `percepcao_conjunta` está `ativo: False` em `configs/base.json` e não foi
  exercitado.
- A divergência λ_c (defeito 1) assume que o `.pyx` **é** o caminho de produção.
  Se o runtime cair para o `.py` por falha de build, a divergência é inócua —
  mas então o ganho de velocidade do Cython desaparece, e o README reporta
  o `.pyx` como o caminho rápido.
- `[PROVADO]` = executado neste sandbox, output reproduzido em
  `verificacao/`. Ausência de marcador = leitura de código.

---

## 14. v15.1 — Auditoria de segunda ordem: corrigir as correções

A camada de correções (patches) e a integração na produção foram elas mesmas
auditadas — com o mesmo rigor da Seção 2–7. **Sete defeitos novos foram
provados e corrigidos.** Moral do capítulo: correção sem verificação é só
outro rascunho.

### 14.1 Os 7 defeitos de segunda ordem [TODOS PROVADOS e CORRIGIDOS]

| # | onde | defeito | prova | correção |
|---|---|---|---|---|
| S1 | `jepa_mundo.py::passo_sonho` | **Admissão INVERTIDA no aquecimento**: `e >= limiar()=+inf` é FALSO ⟹ TODOS os sonhos eram ACEITOS antes de `min_amostras` — o oposto do Teorema 6.1 declarado (a própria Seção 9.1 reportava "86,7% de admissão", inconsistente com "nada é aceito") | execução: 60 sonhos no aquecimento ⟹ aceitos 100% | bloqueio EXPLÍCITO de aquecimento (`len(erros) < min_amostras ⟹ rejeita`); Teo 6.1 agora vale na forma exata |
| S2 | `jepa_mundo.py::limiar` | O "quantil" era a **média dos maiores ⌈q·n⌉ erros** — situa-se acima do quantil q (taxa de admissão ≈86% com q=0.6) | `limiar(q=0.6)` ≠ `np.quantile(erros, 0.6)`; admissão 0.537 vs 0.86 antiga | quantil EXATO por interpolação linear; taxa estacionária ≈ q **[VERIFICADO: 0.537 ≈ 0.6]** |
| S3 | `jepa_mundo.py::passo_sonho` | Sonho SEM contexto entrava com `e=0` (auto-comparação) e **peso 1.0 na memória** — poluição gratuita do SOM | caminho `emb_contexto=None` aceito com peso máximo | sem sinal de erro ⟹ medido, contabilizado, NÃO admitido (relatório §7.1-iii) |
| S4 | `jepa.py::taxa_sucesso_media` | **Placeholder 0.5** — a tabela de μ (Teo 5.6) nunca se adaptava; `historico` sem teto (fuga de RAM em treino de 9 h) | leitura + execução: μ constante 0.9999 | deque com teto (`janela_telemetria`); taxa REAL alimenta `tabela_mu`; **[VERIFICADO: μ=0.9997 com taxa 0.023]** |
| S5 | `jepa.py::mascara_contexto` + `EncoderAlvoEMA` | Parâmetros órfãos: `tau` recebido e ignorado (horizonte era ficção); `warmup` morto (rampa não existia) | leitura: `tau` não aparece no corpo | `eps ∈ {τ..τ+eps_max}` (horizonte ≥ τ, Teo 5.4-b); rampa μ_t = μ·t/warmup **[VERIFICADO: μ(1)=μ/warmup]** |
| S6 | `jepa.py::FunilLatente` | **VOG com lote 1 ⟹ NaN**: `std(dim=0)` com ddof=1 divide por zero | `FunilLatente(16,8)(torch.randn(1,T,16))` ⟹ ‖∇‖=NaN (warning do PyTorch) | `correction=0` (desvio populacional) + piso 1e-4; **[VERIFICADO: ‖∇funil‖=7.1e-01]** |
| S7 | `verificar_tudo.py` §5 (original) | Teste **insatisfazível**: exigia gradiente em modalidades AUSENTES (sem entrada não há caminho no grafo — impossível sem acoplar logits via softmax global, o que quebraria o nascimento neutro) | construção | check corrigido: zero parâmetros mortos ENTRE AS PRESENTES; ausentes com grad None é o CORRETO |

### 14.2 A equação de λ_c, agora ÚNICA (defeito 1 fechado)

`patches/correcoes.py::lambda_c_unica` ≡ `src/khtst/quanta/gsq_rco.py::lambda_c_autoajustavel`
— mesma busca de candidatos no intervalo vazio, mesmo custo rate–distortion.
**Equivalência: 206/206 espectros idênticos** (6 nominais + 200 sintéticos:
lei de potência, exponenciais, Dirichlet, ruído).

Valores no espectro liso (onde o `.pyx` antigo devolvia a constante 0.05):

| espectro | `.pyx` antigo | v15.1 (equação única) |
|---|---|---|
| `1/k^1.2`, d=32 | 0.0500 (trilho) | **0.4200** |
| `1+0.001k`, d=32 | 0.0500 (trilho) | **0.4979** |
| Dirichlet(64), d_real=192 | 0.0500 (trilho) | **0.5860** (ancorado, K̃=12) |

Propriedades do Teorema verificadas sob o custo RAM: φ∈(0,1); K*(λ)
não-crescente; K*(0⁺)=d e K*(1⁻)=1 **no limite** (com cauda quase-nula, K*=d
vale só em λ→0 — a prova do endpoint é por limite, não por λ=0.02: J(K<d)<J(d)
quando ε²(K) < λ·b̂(d)/(1−λ)); ancorado ⟹ K̃ atinge min J_λ* (tolerância 1e-9
para empates de fronteira).

### 14.3 Rate–distortion em números (defeito 2 fechado)

Custo corrigido: `c(K) = log₂K + K·d_real·bits_por_param/n_amostras` bits
(código de entropia + codebook amortizado) — sem denominador `log₂d`.
Mesmo K=4: 2.5 bits (d=8) → 258 bits (d=4096); o modelo antigo dizia
0.667→0.167 (invertia a direção do custo real).

Espectro Dirichlet(64), varredura K sob custo RAM explícito:

| d_real | K* | custo RAM (params) | bits totais | ε²(K*) |
|---|---|---|---|---|
| 64 | 23 | 1.472 | 27,5 | 0,233 |
| 512 | 21 | 10.752 | 172,4 | 0,264 |
| 4096 | 21 | 86.016 | 1.348,4 | 0,264 |

**K* não-cresce com d** (23→21→21) — o critério agora reage à dimensão na
direção certa: codebook maior ⟹ K* menor ou igual, nunca o contrário.

### 14.4 Gate de fusão vivo — e por que 2·sigmoid (defeito 4 fechado)

`g_m = 2·sigmoid(ℓ_m)`, `kv_m = proj_m(emb_m)·g_m`, residual `+ancora·g_ancora`:
  • **nascimento neutro**: ℓ=0 ⟹ g=1 ⟹ saída bit-a-bit idêntica à fusão sem
    gate **[VERIFICADO: Δ=0.00e+00 contra a referência sem gate]**;
  • **gradiente vivo com 1 modalidade**: softmax de 1 elemento teria gradiente
    IDENTICAMENTE nulo (softmax([x])≡1) — sigmoid não **[VERIFICADO: 4/4 casos
    (1,2,3,6 modalidades) sem parâmetros mortos presentes; gate move 0.4274 em
    200 passos SGD(5.0)]**;
  • modalidades ausentes: grad None é o correto (sem caminho no grafo) —
    acoplá-las via softmax global violaria o nascimento neutro.

### 14.5 Viés multiplicativo do roteador (defeito 5 fechado)

`ν = λ_rota·max(0, log(n·conf)/log n)²`, aplicado como `s·(1+ν)` com identidade
neutra 1.0. **[VERIFICADO]**: ν(1/C)=0; ν(conf<1/C)=0; ν(1)=λ_rota; monotono;
consumidores (`moe.py` ×2) migrados de `s+viés` para `s·viés` — o teste v6
(Teo 18.1/18.2/18.6) foi atualizado para a semântica multiplicativa (48 ✓).

### 14.6 Integração no treinador — 3 bugs de integração achados pelo smoke

O requisito "descobrir falhas de integração com dados reais" produziu o
`scripts/18_smoke_v15.py`, que pegou o que as suítes unitárias não veem:

| bug | sintoma | causa | correção |
|---|---|---|---|
| I1 | `drift_alvo = 0.0000` — o alvo EMA nunca se move | motor JEPA construído DEPOIS do otimizador ⟹ funil+predictor fora dos param_groups | construção do motor ANTES do otimizador + `extra_adam` na fábrica MuonClip |
| I2 | gradiente do caminho JEPA descartado silenciosamente | `pcgrad_duas_perdas(self.modelo, …)` só via parâmetros do modelo | lista de params inclui `motor_jepa.parameters()` |
| I3 | alvo EMA poderia enxergar encoder já atualizado | `passo_pos_backward` sensível ao relógio de acumulação | executado APENAS no micro-lote final (mesmo relógio do `step`) |

**[VERIFICADO pós-correção]**: 3 passos reais com `λ_jepa=0.5` — perda finita,
`drift=0.0061>0`, μ=0.9999 seguindo a taxa real, telemetria `jepa/*` viva;
com `λ_jepa=0` nenhum parâmetro novo (nascimento neutro).

### 14.7 JEPA em números (após todas as correções)

encoder sintético (6,12,16), 500 passos AdamW(1e-3), seed 2026 (determinístico):

| passo | perda | var. latente | taxa sucesso | μ |
|---|---|---|---|---|
| 0 | 4,525 | 0,97 | — | — |
| 499 | **2,295 (−49,3%)** | 0,93 | 0,023 (REAL) | 0,9997 |

Sem colapso (var O(1)); telemetria com teto (500 passos ⟹ janelas=100).
Ciclo: sonda de entropia real H/log V = 0,996 sobre entrada real (nunca 0,5);
autorrecompensa Δp·coerência registrada no traço e no hub.

### 14.8 Verificação final consolidada

| camada | resultado |
|---|---|
| `patches/verificar_tudo.py` (9 seções) | **49 ✓ / 0 ✗** — 3 execuções determinísticas |
| equivalência λ_c produção ≡ verificação | 206/206 espectros + hash SHA-256 igual |
| suítes do repo (v1–v14) | **todas verdes**: 25, 36, 37 ✓ (v1–v4); 32 ✓ (v5); 48 ✓ (v6); 44 ✓ (v7); 21 ✓ (v9); OK (v10); ✓ (v11); 28 ✓ (v12); 27 ✓ (v13); 40/40 ✓ (v14, T27.6 atualizado ao custo corrigido) |
| smoke de integração (`scripts/18`) | **13 ✓ / 0 ✗** (3 bugs de integração I1–I3 pegos aqui) |
| teste com DADOS REAIS (`scripts/10`) | **APROVADO** — 32 registros reais de 5 famílias, 3 passos com perda estável, classificador de protótipos acc 1,00 (uniforme 0,083), DPO com 12 pares reais hh-rlhf (acc 0,75), estado 81,3 MB < 900 MB reload bit-exato |

### 14.9 O que NÃO afirmo nesta versão

- A corrida longa de 9 h continua pendente — as projeções de ganho JEPA
  (Δppl/1000 passos) seguem conjecturais até o A/B.
- `perda_sonho_treino` (L_sonho com gradiente) está implementada e verificada
  isoladamente; o gancho no laço de treino completo exige difusão real
  (diffusers) e fica para a corrida longa.
- A autorrecompensa é TELEMETRIA DE SINAL (traço + hub) — a injeção de
  gradiente por reforço no caminho da ação (§10) permanece proposta.
- O caminho Cython (`.pyx`) de `criterios` deve espelhar `lambda_c_unica` na
  próxima compilação — hoje a produção Python já usa a equação única, e o
  teste de equivalência (206 espectros + SHA-256) travará qualquer divergência
  futura.

## 15. v16 — KHMAMBAJEPA: torchao real · MC-JEPA Cython · autorregulação total · robô+matemática

A v16 empilha a camada JEPA de larga cobertura sobre o v15.1, com o
requisito "priorizar Cython", quantização torchao REAL com detecção
automática CPU/GPU e a autorregulação de TODO parâmetro no treino E na
inferência. Provas completas em `docs/matematica/28`; plano/memória em
`PLANO_KHMAMBAJEPA.md`.

### 15.1 Descobertas e provas novas (doc 28)

| # | achado | prova | verificação |
|---|---|---|---|
| T28.1 | cota do erro de quantização uniforme: RMS ≤ h/√12 (por canal, b bits) | momento central da uniforme no bin | medido 3.9e-3 ≤ teórico 3.9e-3 |
| T28.2 | peso torchao é CONSTANTE (inferência-only) | subclass Int8Tensor sem gradiente | compressão 3.92× (78.8→10.1 MB de peso) |
| T28.3 | exclusões obrigatórias: lm_head (sensibilidade exponencial da softmax), especialistas MoE (`torch.stack` não implementado no subclass — descoberto PELA suíte), camadas finas (erro relativo dominante) | Weyl multiplicativa + despacho ausente | forward pós-quant OK; quantizar MoE reproduzia a falha |
| T28.4 | rollback atômico FP32 | cota superior (erro 0) | dim_minimo=99999 ⟹ FP32 intacto |
| T28.9 | gradiente ANALÍTICO do VICReg (o rascunho calculava a perda SEM gradiente): variância com CANCELAMENTO EXATO do centro (Σ centrado = 0); covariância na forma fechada (X̃C)−C_bb·X̃ com projeção de centro NÃO cancelável | eqs. 28.12–28.14 | FD sem-kink 4.2e-11; ≡ autograd torch 9.6e-9; **o fator ½ que duas verificações inconsistentes mascararam foi EXPOSTO pelo FD e corrigido** |
| T28.10 | guarda anti-colapso do passo Brain-JEPA (o rascunho treinava colapsado): φ = frac{σ_j < 0.1γ} > 0.5 ⟹ REJEITA | colapso total é ponto fixo ruim de L_inv | φ=1.0 rejeita; treino real: colapso 0.0 |
| T28.5–28.7 | autorregulação Robbins–Monro MULTIPLICATIVA (log-escala): Σa=∞, Σa²<∞ ⟹ convergência q.c.; duas escalas (Borkar); sinais lr (progresso padronizado), λ (razão aux ≤ ½), MoE (entropia das frações) | RM/Ljapunov + Hedge | convergência 0.9978 no campo 1−x; treino real demo: λ_moe_lb 1.00→1.74, lr 1.00→1.04 |
| T28.8 | temperatura de inferência por ENTROPIA-ALVO: H(T) monótona (dH/dT = Var_p(z)/T²), raiz única, bisseção contrátil (erro ≤ (T_max−T_min)/2^k) | doc 21 Teo 21.4 | H(T_cal)=5.0045 (alvo 5.0); integrada em `gerar(temperatura_auto=)` |
| T28.8-b/c | matemática com resposta canônica = sinal de erro ZERO (verificável); instrução do LeRobot é REAL (meta/tasks.parquet — fetchman: 902 instruções) | igualdade canônica | 240 registros de matemática + 43 de robô coletados de verdade |

### 15.2 Tarefas canônicas 12 → 14 (Teo 22.1 preservada)

`robo` (grupo visual — câmeras LeRobot) e `matematica` (grupo textual)
entram pela FONTE ÚNICA; `n_intencoes = len(TAREFAS)+1 = 15` dinâmico;
prefixos `[robo]`/`[math]` no BPE; mistura renormalizada. As suítes
v11/v12 que hardcodavam "12" foram migradas para `len(TAREFAS)`.

### 15.3 Datasets v16 (coleta REAL, orçamento honesto)

283 registros novos (corpus merge 903): fetchman 40 · gsm8k 40 ·
MATH-500 40 · hendrycks álgebra 40 · hendrycks number_theory 40 ·
OpenR1 40 · IFM 40 · robô com frame 3. **Degradados documentados**:
`heatherwhite/math-collection` (só metadata_sample.jsonl — dados reais
fora do Hub) e `3DTopia/4DNeX-10M` (tar.gz ~680 MB, gzip não amostrável
por HTTP Range). Frames de câmera: ≤4 mp4/fonte com HEAD prévio; meta
documenta quando o frame não veio — NUNCA imagem inventada. Defeito de
integração achado no smoke: `trust_remote_code` foi REMOVIDO do
datasets 5.x (o caminho antigo falhava imediatamente) — dispatcher
corrigido.

### 15.4 A/B pareado real (120 passos, corpus 903, lote 4)

| variante | perda início → fim | melhoria | held-out | observações |
|---|---|---|---|---|
| baseline v15 | 9.769 → 5.395 | **1.811×** | 6.697 | v15.1 exato |
| v16 JEPA+VICReg(0.3)+autorreg | 9.713 → 6.679 | 1.454× | — | razão aux 0.8 VIOLA Teo 28.7-ii |
| v16 JEPA+VICReg(0.1)+autorreg | 9.724 → 7.501 | 1.296× | 7.420 | razão aux 0.27 ✓ cumpre a cota |

**Leitura honesta:** o baseline converge mais rápido em CE; a própria
teoria explica (PCGrad com termo auxiliar dominante) e prescreve o
ajuste (λ≤0.1). O que a v16 compra: representação sem colapso
(var_latente 0.70), **torchao com Δperda 0.000** (int8 REAL 3.92× sem
perda medível), autorregulação viva nos dois regimes, kernel Cython
verificado, 14 tarefas com sinal verificável. Comparação definitiva de
CE: corrida de 9 h (protocolo do README).

### 15.5 Estados e higienização

Estados de treino ANTERIORES: nenhum no Hub (209 arquivos, zero
.safetensors/.pt/.ckpt) nem no ambiente (busca ampla) — auditoria
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.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✓.

## 17. v18 — Robustez (§1–3 do requisito), IPC Modelo→Modelo (Rust/Cython) e família JEPA + SonicMoE + ReplaySSM

**Entrada**: requisito v18 — falhas remanescentes (1.1.1–1.1.5), aprimoramentos
matemáticos (2.1–2.5), melhorias lógicas (3.1–3.4), módulo de comunicação
Modelo→Modelo em Rust/Cython, família JEPA (10 variantes) + SonicMoE +
ReplaySSM em hardware chinês/CPU, plano Markdown com provas e memória .md.

**Robustez (doc 30 §§1–2, Teos 30.1–30.6):**
- **30.1/3.1** — guarda de ordem EMA do JEPA: contador `_passos_sem_ema`
  (tolerância = lote efetivo) lança `RuntimeError` quando
  `passo_pos_backward()` não segue o `optimizer.step()`; implementado no
  `MotorJepa` (produção) e no `JEPA` v17 (forwards com gradiente apenas —
  avaliação sob `no_grad` não conta). Viés provado: O((1−m)·η·G) por passo.
- **30.2/2.4/1.1.5** — kernel Mamba-3 com clamps δ∈[1e-6,1−1e-6], A≤−1e-6
  (contração SEMPRE; identidade na região válida ⟹ gradiente autograd
  intacto) + `verificar_estabilidade` para telemetria de anomalias.
- **30.3/2.3/1.1.4** — `NormalizadorPerdas` (EMA por chave, fator =
  clip(EMA_CE/EMA_aux, 0.1, 1.0), warmup 20, nascimento neutro) aplicado a
  TODAS as 8 auxiliares antes do PCGrad — cota de dominação ≤ 10× (prova
  com ‖h′‖ ≥ ‖h‖·sinθ).
- **30.4/2.2** — Newton-Schulz com precisão adaptativa: fp32 quando
  ‖G‖_F < 1e-3 (erro angular cai ~3.3e4×), bf16 preservado caso geral.
- **30.5/2.1/1.1.2** — `weight_decay_muon=1e-4` desacoplado (shrink
  multiplicativo comuta com a decomposição polar; controla ‖W‖_* sem
  lutar com a ortogonalização).
- **30.6/2.5** — GSQ τ_min 0.25→0.5 (Jacobian ≤ 1/(4τ) ≤ 0.5 — 2^L menos
  amplificação em L camadas), t_alvo 600→400 (T_τ = 400/ln30 ≈ 117.6);
  fonte única de constantes (`TAU_MIN_PADRAO`/`T_ALVO_PADRAO`) propagada
  aos 3 pontos de chamada.

**Lógica (doc 30 §§0/3, Teos 30.7–30.8, requisito §3.2–3.4):**
- **30.7/3.3** — `nucleo/validacao.py`: `validar_config` + `exigir_config_valida`
  (pré-condições dos teoremas a montante; aborta ANTES do treino; chamada
  na 1ª linha do `TreinadorExtensao.__init__`).
- **30.8/3.4** — `telemetria/log_estruturado.py`: níveis DEBUG/INFO/WARNING/
  ERROR em JSONL, rotação por tamanho (5 MB × 3 backups, custo amortizado
  O(1)), eco de WARNING/ERROR no stderr; hub integrado (histórico `deque`
  limitado — vazamento de memória eliminado; NaN/Inf → `hub.alerta`;
  QK-clip e colapso latente viram WARNING).
- **1.1.3/3.2** — treinador refatorado: 4 mixins (lr/perdas/estado/fases)
  com métodos movidos VERBATIM + facade `TreinadorExtensao` (API pública
  intacta; 92 KB → 66 KB + 4 módulos focais). Regressão v1–v17 TODA VERDE
  após o movimento (evidência de preservação comportamental).

**IPC Modelo→Modelo (doc 30 §4, Teos 30.9–30.10, requisito):**
- Crate Rust completo (`src/khtst/ipc/rust/`: memfd selável, RingBytes
  SPSC, io_uring, socket SCM_RIGHTS, framing, FFI cbindgen) — código do
  usuário preservado e organizado em crate.
- Produção em Cython (`khtst_ipc.pyx`, compila SEM cargo): memfd +
  seals, ring SPSC com atomics C11/GCC (`__atomic_*`, acquire/release —
  mesmo contrato de memória do Rust), layout binário idêntico (header
  64 B, magic 0x4B485453); fallback puro-Python honesto; framing Python
  (header 24 B "<IBBHQII" + CRC32).
- **Bug de integração capturado**: ring SPSC não é bidirecional — a 1ª
  demo com UM ring fazia o filho consumir os próprios pedidos (servidor
  via 0 frames). Correção: DOIS canais (um por direção) — regra R18.4.
- Demo APROVADA (`scripts/21_teste_ipc.py`): 2 processos, SCM_RIGHTS,
  64 pedidos ecoados com verificação byte a byte, 0 descartes,
  CRC32 rejeita corrupção.

**Família JEPA + SonicMoE + ReplaySSM (doc 30 §5, Teos 30.11–30.15):**
- `jepa_familia/` — 10 variantes (Image, V-JEPA2, MC, Audio, Point, 3D,
  Brain, T, Le, BJEPA) com EMA + guarda de ordem + anti-colapso por
  dimensão; `ConselhoJepas` multimodal com gating renormalizado e
  nascimento neutro; treino ponta a ponta 10 modalidades (L 1.19→0.82
  em 5 passos de teste).
- `sonicmoe.py` — dispatch agrupado por expert + tiles + int8 opcional +
  telemetria IO (medido: 64× menos bytes de pesos que o ingênuo no teste).
- `replayssm.py` — reservoir de estados com re-injeção h₀ + drift;
  uniformidade do reservoir verificada por Monte-Carlo (600 simulações);
  h₀=0 ≡ kernel padrão (allclose 1e-6).
- `dispositivo.py` — NPU Ascend / MLU Cambricon / XPU / CUDA / MPS / CPU
  com prioridade para hardware chinês e degradação honesta (Teo 30.15).

**Verificação**: suíte v18 NOVA — **46/46 verdes** (doc 30 citado em cada
verificação); regressão v1–v17 TODA VERDE (25/36/✓/37/32/48/44/21/✓/✓/28/
27/40/—/✓/56); demo IPC 2 processos aprovada.

## 18. v19 — Acoplamento JEPA↔encoders de produção (A/B pareado) + SonicMoE no tronco (opt-in) + datasets reais

**Entrada**: requisito v19 — "acoplar as variantes JEPA aos encoders de
produção com A/B pareado; ativar SonicMoE no tronco (opt-in) e rodar testes
de datasets reais para averiguar funcionalidades". Fonte: doc 31 (Teos
31.1–31.7 + regras R19.1–R19.8).

**Acoplamento JEPA↔encoders de produção (doc 31 §§1–3, Teos 31.1–31.3):**
- `jepa_familia/acoplamento.py` (NOVO): vistas de tokens `VistaTokensImagem/
  Audio/Video` que chamam os MÓDULOS do encoder de produção SEM cópia
  (proj/pos/cls/blocos/bigru/norm; log-mel/convs; CLS por frame) —
  **Teo 31.2**: o gradiente JEPA é a regra da cadeia EXATA sobre os pesos
  reais do encoder (autografa por identidade de tensor); **31.2-cor**: os
  parâmetros do encoder ficam FORA do grupo extra AdamW (filtro por
  identidade — registrá-los duas vezes aplicaria dois passos ao mesmo θ).
- Alvo EMA = deepcopy no nascimento (θ̃←m·θ̃+(1−m)·θ APÓS optimizer.step());
  **Teo 31.6**: guarda de ordem EMA por variante (tolerância = lote_efetivo,
  RuntimeError na violação — mesmo contrato do MotorJepa/Teo 30.1).
- **Teo 31.3**: conselho renormalizado = média convexa com nascimento neutro
  (gating softmax uniforme no nascimento; variantes sem lote no passo são
  excluídas e os pesos renormalizados).
- Integração no treinador: perda do conselho via `_aux_norm` (Teo 30.3
  anti-dominação), parâmetros novos no PCGrad, telemetria `jepa_ac/*`.

**SonicMoE no tronco (doc 31 §§5, Teos 31.4–31.5, opt-in):**
- Gate extraído para `_computar_gate` (refatoração VERBATIM — Teo 31.1:
  gate bit-idêntico, Δg=0.000e+00 medido).
- `forward_sonico`: dispatch agrupado por expert + GEMM em tiles +
  telemetria IO. **Teo 31.4**: equivalência sônico≡vetorial (saída,
  gradientes, L_lb/L_ort/_Z_ultimo) — medido: Δy=3.0e-08, Δgrad_x=3.4e-08,
  Δgrad_w=2.1e-07, ΔL_lb=0.
- **Teo 31.5 (roofline HONESTO)**: com o gate foco atual (softmax sobre os
  ativos), Σ_e n_e = A·BT — fator_trabalho=1; o ganho real é de IO de
  PESOS (pilha `torch.stack` evitada: 2.21 MB/forward; ganho modelado
  2.0×). Wallclock CPU medido: 0.83–0.875× (sônico mais lento nesta
  escala — overhead do laço em GEMMs pequenos; reportado como está).
  31.5-nota: se o gate tornar-se esparso por token, o mesmo código passa a
  omitir linhas automaticamente.
- Wiring: `modelo.sonicmoe {ativo, tile_m}` (default DESLIGADO) — nasce
  neutro (Teo 31.1); atua só na fase FOCO (R19.7).

**A/B/C PAREADO em datasets reais (doc 31 §§7/9, Teo 31.7):**
- **Pareamento EXATO**: re-seed pós-construção + máscaras JEPA com
  gerador DEDICADO + conselho em eval — o fluxo RNG global dos braços é
  idêntico ⟹ mesmos lotes; ΔCE_t pareado por passo (Teo 31.7).
- Corpus REAL 1015 registros (395 FRESCOS: LeRobot fetchman, GSM8K,
  MATH-500, hendrycks, OpenR1, IFM socratic — orçamento por fonte),
  protocolo 96 passos × 3 braços com retomada por checkpoint (RAM 4 GiB;
  OOM da 1ª tentativa com lote_efetivo=4 documentado e corrigido).
- Resultados: A baseline 9.738→6.064 (1.606×) · B v19 λ=0.3 9.726→6.296
  (1.545×, ΔCE=+0.090) · C v19 λ=0.1 9.732→6.187 (1.573×, ΔCE=+0.046) —
  **monótono em λ** (Cor. 31.7, Teo 28.7-ii). JEPA acoplada APRENDE:
  0.808→0.205 (−74%) e 0.847→0.215 (−75%); drift dos encoders com JEPA
  (8.26e-4/8.75e-4 imagem) > baseline (7.04e-4) — gradiente extra CHEGA
  ao encoder real.
- Gráficos: `graficos/v19/v19_evidencias.png` (3 painéis).

**Correção de processo**: `patches/jepa.py` estava DIVERGENTE da produção
(a guarda Teo 30.1 da v18 não foi espelhada) — hash SHA-256 dessincronizado
detectado pelo `verificar_tudo` (48✓/1✗); sincronizado ⟹ 49✓/0✗.

**Verificação**: suíte v19 NOVA — **34/34 verdes** (doc 31 citado em cada
verificação); verificar_tudo **49✓/0✗**; regressão v1–v18 TODA VERDE
(25/36/✓/37/32/48/44/21/✓/✓/28/27/40/—/✓/56/46).

**O que NÃO afirmamos** (doc 31 §10): benefício de wall-clock CPU do
SonicMoE nesta escala; benefício de CE em 96 passos (o acoplamento custa
≤ +0.09 de CE — benefícios de representação esperados em corrida longa/
probes downstream); economia de linhas com o gate atual (fator_trabalho=1).

## 19. v20 — IPC durável (10 correções do usuário com provas) · estresse + Modelo→Modelo em treino · PID-MoE · Stiefel rígido + polar · GuardaRuntime

**Requisitos cumpridos** (doc `32-v20-ipc-durabilidade-pid-stiefel.md`,
Teos 32.1–32.12 + regras R20.1–R20.10):

1. **IPC v20** — as 10 correções prescritas, cada uma com prova e teste:
   - *cache-line padding*: header 64→256 B, `head@64/tail@128/dropped@192`
     (Teo 32.1 — MESI: tráfego destrutivo 2·min(λp,λc)→essencial);
     replicado no Cython e no fallback; asserts `offset_of!` em
     compile-time no Rust.
   - *io_uring honesto*: `push_send_fd` REMOVIDO (SCM_RIGHTS é cmsg de
     sendmsg — a v18 enfileirava Writev vazio e não entregava FD; Teo
     32.5); `pending.clear()` no reap (Teo 32.6).
   - *framing*: CRC32 verificado no decode (Teo 32.4: burst ≤32, peso
     ímpar, resíduo ≤2⁻³²) com tabela const — sem dependência nova;
     `payload_len` com bounds check (antes: slice fora dos limites ⟹
     pânico); `read_unaligned` no encode (packed sem UB, Teo 32.4-cor).
   - *robustez*: EINTR retry em sendmsg/recvmsg (Teo 32.7 — EINTR não é
     erro); magic validado na init ANTES de selar (Teo 32.2 — re-init de
     região viva zeraria head/tail sob o consumidor; ordem v20 evita o
     EPERM opaco de seals re-adicionados); ring cheio ⟹ **BufferError**
     com escrita atômica por predicado de espaço (`write_exact`/Teo 32.3);
     THP `madvise(MADV_HUGEPAGE)` ≥ 2 MiB nos dois lados (Teo 32.8);
     resíduo do consumidor com `_PEND_MAX`=4 MiB (Teo 32.9).
   - *bug adicional capturado pelo estresse*: `receber_frame` v18
     descartava os frames extras extraídos do ring na mesma leitura
     (perda silenciosa de dados VÁLIDOS) — v20 mantém `_fila_frames`.
2. **Estresse IPC** (`scripts/28_teste_ipc_stress.py` — APROVADO):
   T1 21 frames 1 B→1 MiB (geométrica ×2) em 2 processos; T2 round-trips
   byte a byte + CRC; T3 ring cheio → BufferError isolado, drenagem
   íntegra, retry OK; T4 latência escrever+ler: média 23,0 µs, **p50
   21,4 µs, p95 30,4 µs, p99 45,2 µs** (payload 512 B, n=2000).
3. **Modelo→Modelo DURANTE treino** (`scripts/29_ipc_treino_modelo.py` —
   APROVADO): 2 processos, cada um com KHTST real (d=64, 6 camadas 5:1,
   vocab 512) treinando 60 passos reais (forward+backward+step); telemetria
   (passo, perda, grad_norm) trocada a cada 5 passos pelos 2 rings SPSC;
   **uso funcional**: fator de lr de cada modelo acoplado à perda do peer
   (não é eco decorativo). Resultado: 12/12 frames por direção, 0
   descartes, ambos aprendem (A 1,019×, B 1,024×), fatores finitos
   0,999/1,001 — canal vivo em treino real.
4. **PID-MoE** (reqs 1.8/2.7 — `nucleo/pid_moe.py` + wiring no treinador,
   Teo 32.10): re-peso multiplicativo λ_lb·u com u saída de PID discreto
   em log-escala sobre o desvio de carga D=max f_i−1/N; anti-windup
   direcional (integral só acumula quando empurra para dentro da faixa);
   nascimento neutro (ativo=False ⟹ u≡1, v19 exato); limites [0,25;4]
   preservam a dominância da CE. Suíte: colapso sintético D=0,9 ⟹
   u 1,0→2,0 no primeiro passo, saturação 4,0 sem windup.
5. **Stiefel rígido + retração polar** (reqs 1.9/2.6/3.5 —
   `percepcao/ortogonais.py`, Teo 32.11): renormalizar() tenta QR; em
   falha/NaN/desvio>tol recorre à retração polar Q=UVᵀ (ARGMIN de
   ‖W−Q‖_F sobre Stiefel — prova por von Neumann: max_Q tr(QᵀW)=Σσ_i);
   último recurso identidade; `afirmar_ortogonalidade()` e
   `treino.ortogonal_rigido` abortam em violação (bug real de Stiefel
   nunca mais silencioso). Medido: pós-QR 4,8e-7; W com NaN recuperado.
6. **GuardaRuntime** (req 3.6 — `nucleo/guarda_runtime.py`, Teo 32.12):
   OLS do RSS (VmRSS de /proc) em janela deslizante com cota e somas
   correntes O(1); alerta SOMENTE com janela cheia (Var[β̂] ∝
   12σ²/s²J(J²−1) — janelas parciais produzem falsos positivos, capturado
   pela suíte); vazamento sintético 2000 MB/1k detectado (β̂=2000, 29
   alertas); RSS estacionário β̂=1,0 sem alerta; opt-in (zero custo).

**Verificação**: suíte v20 NOVA **48/48 verdes** (inclui 10 auditorias de
fonte Rust); estresse + demo Modelo→Modelo APROVADOS; verificar_tudo
**49✓/0✗**; smoke v15 ✓; regressão v1–v19 TODA VERDE
(25/36/✓/37/32/48/44/21/✓/✓/28/27/40/—/✓/56/46/34) — todas as mudanças
nascem neutras (opt-in) e são comportamento-preservantes.

**O que NÃO afirmamos** (doc 32 §11): ganho de THP medido isoladamente
(hint best-effort — prova estrutural); speedup do cache-line padding no
sandbox (exige pinagem de núcleos); benefício end-to-end do PID-MoE em CE
(depende da distribuição de carga — A/B pareado fica para a corrida
longa); CRC-32 não substitui ECC — é segunda linha de defesa.

## 20. v21 — Fonte única do IPC (Rust removido, layout compile-time) · Newton–Schulz espectral certificado · imagem adaptativa · hot-paths Cython · tabela v17 fechada

**Requisitos do usuário atendidos** (refatorações 1–3, melhorias 1–3, PLANO
itens 5–6, treino real, remoção de deprecados):

**IPC — fonte única (doc 33 §2, Teos 33.1/33.2).** O crate `rust/` foi
EXCLUÍDO (3ª implementação redundante do mesmo ABI — auditoria DRY do
usuário aceita); o layout do header (256 B) e do frame (24 B) agora tem
FONTE ÚNICA (`khtst/ipc/layout.py`) com DUAS camadas de verificação:
`_Static_assert` (C11) sobre a struct espelho no `.pyx` — 8 asserts no C
gerado, divergência NÃO COMPILA — e auditoria binário↔layout.py no import
(.so velho falha com erro explícito). O fallback puro-Python importa as
constantes da fonte (zero duplicação). Suíte v21 §1 + estresse v20
permanecem verdes.

**Newton–Schulz espectral (doc 33 §3, Teos 33.3–33.6).** A v18 assumia
σ₁ no Teorema 24.1 mas normalizava por ‖X‖_F no código (lacuna achada na
auditoria do usuário). A v21 normaliza por
s = min(√‖A₀‖∞/1.2, ‖X‖_F) com A₀ = XXᵀ em fp32: segurança CERTIFICADA
(λ₁ ≤ ‖A‖∞ por normas induzidas; janela invariante (0, 1.255] da quíntica
provada por pontos críticos), NUNCA pior que v20 (o `min`), e escala de
partida 1.2·σ₁/√‖A‖∞ ≥ v20 — nos perfis medidos (pico/exp/plano/mp) a
escala melhora até ~4.6× e os σ pequenos sobrevivem (Teo 33.6); custo
+27% no NS (1 Gram fp32, reusado na 1ª iteração). Sem RNG, sem SVD, sem
iteração de potência.

**Imagem adaptativa (doc 33 §5, Teos 33.7–33.10).** Fonte única
`percepcao/redimensionar.py` nos 3 call sites (treinador, jepa_mundo,
difusao): letterbox (similaridade — nenhuma distorção; kill-switch repõe
v20 bit-a-bit), LANCZOS antialias (Nyquist controlado), janela saliente
por energia de arestas para razões > 2.5 (condicional ρ=0.6, O(W),
determinística) e upscale limitado a 2× (neutralidade I(X;U(X))=I(X;X)).
Bug REAL achado e corrigido durante o desenvolvimento: `total` da energia
era a soma sobre janelas (~alvo× a energia) — as frações nunca passavam;
corrigido para a energia total 1×.

**Hot-paths Cython (doc 33 §6, Teos 33.11–33.13).** `acelerado/
mamba3hot.pyx`: conv depthwise causal FUNDIDA (1 leitura+1 escrita vs 5
passadas; ganho medido 2.34×/4.61×/7.58× nas formas B4L128D192/
B8L512D512/B2L1024D768; equivalência max|Δ|=0) com backward ANALÍTICO
exato (autograd.Function; u/b Δ<1e-4, w 5.8e-7 relativo); top-k parcial
O(N·k) do roteador (valores idênticos ao torch.topk; desempate
determinístico; ganho 1.19–1.81× nas formas do gate — honesto: torch
ganha 2.6× em N=64 k=8, fora do escopo do gate). Fallback v20 automático
(dtype/device/binário) + kill-switches de config. Wired em
`Mamba3Camada`, `Mamba3VLModelo` e `MoEAgrupavel._computar_gate`
(seleção sem gradiente — seguro por construção).

**Tabela v17 fechada (doc 33 §7, Teo 33.14).** O
`AutorreguladorEstendido` (18 controladores, Teo 29.16) estava SEM
chamador; agora o `_ciclo_autorreg_v17` produz 8 sinais REAIS (CV² do
gradiente, norma-peso relativa à inicialização, trust do PRS, Δperda,
razão de clips, razão L_moe/L_ce, logit_max das NoPE) e aplica nos
param_groups (β₁/β₂/ε/wd, momentum/escala, τ_qk) e no PRS (5 parâmetros).
Nascimento neutro: `ativo=false` (default) ⟹ v20 exato; `espera=20` e
limites seguros da tabela; os 10 sinais sem produtor barato ficam com
sinal 0 (honestidade, doc 33 §11).

**Nota de auditoria (doc 33 §8).** A suspeita de typo `etade` em
`indicadores.py::estagnado` era ARTEFATO DE EXIBIÇÃO (dump octal:
`min(janela_perda[metade:])` correto); nada alterado.

**Verificação.** Suíte v21 NOVA 40/40; regressão v1–v20 TODA VERDE
(25/36/✓/37/32/48/44/21/✓/✓/28/27/40/—/✓/56/46/34/38);
verificar_tudo 49✓/0✗; deprecados removidos (rust/, artefatos v6/v7/v10
da raiz).

**A/B/C/D pareado REAL** (scripts/31_teste_v21.py, 48 passos, corpus 1015
registros, pareamento exato Teo 31.7): A baseline_v20 9.728→8.772
(1.109×) · B v21_ns 9.727→8.845 (1.100×, ΔCE +0.073) · C v21_full
9.763→8.720 (**1.120×**, ΔCE **−0.052**) · D v17_ativo 9.766→8.842
(1.104×, ΔCE +0.071). Progresso monótono por quarto em TODOS os braços
(9.73→9.47→9.02→9.12±0.05). LEITURA HONESTA: as diferenças de ΔCE
(±0.07) estão no RUÍDO de 48 passos (B e C diferem só por reassociação
de fp nos kernels equivalentes) — o valor da v21 é a correção teórica do
NS + segurança certificada + unificação IPC + wallclock dos hot-paths +
fechamento do laço v17, não salto de CE em corrida curta; o A/B longo
fica para a corrida 9h.

**O que NÃO afirmamos** (doc 33 §11): cota ∞ frouxa em espectros planos
caí no branch Frobenius (nunca pior, mas σ̃_max≈1.2 só quando a cota é
apertada); custo +27% do NS (CPU; GPU não medido); top-k Cython perde
fora do escopo do gate; 10/18 sinais v17 sem produtor (sinal 0);
backward da conv de 1ª ordem.

## 21. v22 — Fechamento 18/18 da tabela v17: os 10 produtores restantes com medições REAIS, appliers novos e treino real pareado

**Requisito.** "instrumentar os 10 sinais v17 restantes (v22); testar e
treinar com datasets reais verificando progresso".

**O que foi entregue** (doc 34, Teos 34.1–34.11):

1. **Estado do otimizador — 4 sinais** (`treino/otimizadores.py`):
   acumuladores de ‖passo‖², ‖g‖², ‖v‖², ‖Δv‖² (AdamW) e ‖Ghat‖²,
   ‖buf‖², ‖g‖² (Muon) — **observadores puros** (opt-in
   `coletar_metricas`, sem RNG, sem mutação ⟹ **bit-a-bit v21**,
   Teo 34.1 provado na suíte com trajetória idêntica). Produtores:
   `razao_update_grad` = RMS(passo) (Teo 34.2 — Jensen: |m̂|≤√v̂
   elemento a elemento, ρ≤1/√(1−β^t)→1), `deriva_seg_momento` = RMS(Δv)/
   RMS(v) com calibração pivotal pela própria EMA (Teo 34.4 — alvo 1.0
   sem proxy), `razao_momentum_grad` = √(1−β²)·RMS(buf)/RMS(g) (Teo 34.3
   — piso estacionário E‖b‖²=nσ²/(1−β²)), `razao_rms_mecanismos` =
   RMS(Ghat)/RMS(passo) (Teo 34.5 — Teo 24.11 agora MEDIDO).
2. **Crescimento SOM — contadores reais** (`som_base.py`,
   `variantes_crescimento.py`, `orquestrador.py`): GG/GCS/GSOM contam
   inserções/podas EXATAMENTE quando uma unidade entra/sai (conservação
   k+podas=3+inserções verificada); `contadores_crescimento()` agrega e o
   treinador produz taxas por diferença entre ciclos (Teo 34.8).
3. **ABMO/CIAR/ativacao_som/τ_qk** (mixin `treinador_v22.py`):
   `margem_abmo_norm` = cap/lr_base (Teo 34.6), `taxa_aceitacao_ciar`
   (fração de janelas com melhora — Hoeffding; alimentada no cadence do
   ciclo E no autoajuste, Teo 34.7), `ativacao_som` =
   `taxa_ativos_global()` em QUALQUER fase, e `logit_max` lido DIRETO dos
   módulos a cada ciclo (frescura ≤ a_cada passos vs 20 antes; Teo 34.9).
4. **APLICADORES novos** (`aplicar_em_treinador`, Teo 34.10): margem
   ABMO (clamp ≤1.0 ⟹ cap>0 sempre), κ_ext do CIAR (×[0.25,2.5]),
   λ_inserção e util_poda dos SOMs (sinal de poda INVERTIDO: taxa abaixo
   do alvo ⟹ poda mais agressiva) e `_peso_som_v17` (× normalizado pelo
   centro 0,05 = default de lambda_som). Nascimento neutro por BASE
   CAPTURADA na 1ª escrita — a 1ª aplicação é a identidade mesmo com
   config customizada.
5. **Refatoração estrutural** (Teo 34.11): `_ciclo_autorreg_v17` +
   `_init_estado_v17` movidos VERBATIM para o mixin
   `treinador_v22.py` — restaurado o limite <80 KB de treinador.py
   (suíte v18 46/46 de novo verde). `espera` configurável via cfg
   (default 20 = v21 exato).
6. **Corpus real fresco** (requisito "treinar com datasets reais"): 7
   fontes coletadas NESTA ronda (GSM8K 70, MATH-500 100, OpenR1 100,
   IFM-socratic 60, pontuação PT-BR 700, intel-image 160) → 1015
   registros deduplicados em 4 tarefas; tokenizador retreinado com vocab
   **16384** (constante do projeto).

**A/B pareado REAL** (scripts/33_teste_v22.py, 48 passos, lote 4,
pareamento exato Teo 31.7; braço B com a_cada=5, espera=2): A
baseline_v21 9.812→7.207 (**1.362×**) · B v22_ativo 9.747→7.568
(1.288×, ΔCE +0.3617, s/passo 7.03→7.16). **Auditoria do braço B: 10/10
controladores novos com produtor real MOVERAM** (β₂ ×1.052, ε ×0.754,
momentum ×1.042, escala ×1.005, τ_qk→400 — Teo 34.9-iii: ℓ_natural≈5≪
banda, sem efeito funcional; ABMO ×1.150 com margem REAL 0.25→0.288;
CIAR κ_ext ×0.998; expand ×0.869; prune ×1.150; peso_som ×1.150) e os
appliers escreveram nos alvos reais (`_abmo["margem"]`, `ciar["kappa_ext"]`,
`_peso_som_v17`, λ/util_poda dos variantes). Progresso monótono por
quarto em ambos (A 9.75→9.02→7.85→7.85; B 9.74→9.01→8.03→8.14).

**Verificação.** Suíte v22 NOVA **46/46** (inclui a prova de
neutralidade bit-a-bit com coletar=True/False); regressão v1–v21 TODA
VERDE (25/36/✓/37/32/48/44/21/✓/✓/28/27/40/—/✓/56/46/34/38/40) +
verificar_tudo **49✓/0✗**; IPC .so reconstruído (o binário no git era um
ponteiro LFS de 132 B — artefatos acelerados agora commitados como
binários reais).

**O que NÃO afirmamos** (doc 34 §10): ganho de CE pela tabela ativa em
48 passos (medido +0.36 — 18 controladores movem hiperparâmetros
comprovados com janelas curtas; valor estrutural: fechamento,
observabilidade, segurança; produção continua `ativo=false` até o A/B de
longa duração); τ_qk no teto 400 no modelo de teste (inofensivo);
expansão/poda SOM zeradas na fase A (honesto); custo dos acumuladores
não decompõe as causas dos ~2% de s/passo; o produtor τ_qk da v21 NÃO
estava morto (a v22 generaliza o filtro e aumenta a frescura — não é
correção de bug).

## 22. v23 — Auditoria independente integrada: correções válidas aplicadas com provas, claims refutadas documentadas, corpus sem vazamento

**Fonte:** auditoria externa de 2026-10-17 (7 arquivos: PLANO_MELHORIAS_KHTST.md,
EXECUTAVEL.md, CORRECAO_A01_PCGrad.md, modelo_ram.py, verif_pcgrad_invariantes.py,
verif_pcgrad_rope.py, verif_cinza_lipschitz.py) sobre o espelho v22. O v23
re-verificou CADA claim contra o código real antes de agir — 5 claims caíram
(§11 do doc 35), o resto foi corrigido com provas (doc 35, Teos 35.1–35.14).

**Correções aplicadas (arquivo:linha no commit):**
| Achado | Correção v23 | Prova |
|---|---|---|
| A-01 PCGrad reescala | `fator=dot/n2`, `g=gm+(ga−fator·gm)` (cirurgia_grad.py) | Teo 35.1; suíte v23 §1: 0 violações I1/I2/I3 (398 pares torch; 100.083 numpy) |
| A-03 RoPE sem offset | `desloc` em aplicar_rope + propagação (modelo.gerar, SessaoKHTST, MoA, blocos) | Teo 35.8; suíte v23 §2: prefill bit a bit, translação exata, decode VARIA com t |
| A-04 tronco 3 camadas (0 NoPE) | `n_camadas=6` + validação do campo REAL (validacao.py) | Teo 35.5; suíte v23 §6: L=3 reprovado, L=6 ⟹ 5:1 |
| I-03 checkpoint não-atômico | tmp+fsync+os.replace+fsync(dir); hash obrigatória; apagar por último | Teo 35.3; suíte v23 §3 (a–d) |
| I-01 IPC header nunca lido | anexar valida capacidade (fallback + Cython; .so recompilado) | Teo 35.4; suíte v23 §4 |
| T-02 dedup 29,5% | `_chave_dedup` (texto+entrada+saída+mídia) única nos 3 consumidores | Teo 35.7; descarte 29,5%→8,7% |
| T-03/T-01 splits de avaliação + Fable "lite" | `papel:"avaliacao"` em 9 fontes benchmark (probe datasets-server), hendrycks→train, Fable→train; filtro P9 com evento PULADA | Teo 35.14; coleta real: MATH-500 PULADA, 1612 registros |
| T-08 NFD | NFC na ingestão (idempotente — Teo 35.6) | suíte v23 §5 |
| A-05 acumulação com viés na retomada | divide pelo tamanho REAL do grupo (`_n_acc_atual`) | Teo 35.9; suíte v23 §7 |
| A-19 hub open/close por linha | buffer 64 linhas/2 s + `fechar()` no scripts/04 | Teo 35.10; suíte v23 §8 |
| A-22 avaliar() vazio silencioso | alerta explícito no hub/stdout | — |
| A-23 árvore INERTE desde a v8 | em treino y_a sempre computado; `y+0·y_a = y` bit a bit | Teo 35.13; grad medido no treino real (−14,16) |
| P16 docstring Lipschitz falso | vit_lra.py cita o bound real do Teo 27.7(ii-a) | verif_cinza_lipschitz.py (razão ≤1; 2δ violado 45× no pixel escuro) |
| E-01/E-02 (doc 26) | erratas: Σ1/τ DIVERGE; T_τ=600/ln 35≈168,76 (τ(600)=0,300 confirma) | Teo 35.12; suíte v23 §9a-b |
| E-03/E-04 (doc 28) | erratas: dH/dT=Var/T³ (FD 0,985); h²/12 exige densidade contínua | Teo 35.11; suíte v23 §9c-d |
| P15 scripts sem assert | auditoria hardened em `auditoria_independente/` (assert + exit code, 4/4 verdes) | — |
| P12 suíte torch-dependente | tests/conftest.py: coleta vira skip com mensagem clara sem torch | — |

**Claims da auditoria REFUTADAS contra o código real (não aplicadas):**
E-05 (`perda_lb` é tensor com gradiente — treinador.py:606), I-05
(`razao_moe_ce` produzido no mixin v22 — tabela 18/18 real), A-21 (único
call site da conv profunda é guardado por `_hot is not None` — kernel.py:199),
número 0,1502 do E-04 (internamente inconsistente: E[Δ²] ≤ max|Δ|² = 6,8e-4;
o ponto qualitativo entrou na errata com o contra-exemplo EXATO on-grid).

**Teste real (scripts/36_teste_v23.py + 37_graficos_v23.py):** corpus FRESCO
1612 registros (3 tarefas, P9 auditado — MATH-500 PULADA, hendrycks em train);
A/B pareado exato 48 passos com UMA variável (semântica v≤22 ablation via
monkeypatch vs v23 limpo): baseline 9,671→7,974 (1,213×) vs v23 9,719→8,497
(1,144×), ΔCE +0,134 — leitura honesta idêntica ao precedente v22: os fixes
são de CORREÇÃO com invariantes provados; corrida curta não mede o valor
(que é estrutural: não-piora garantida, posição relativa restaurada, árvore
viva, treino sem vazamento). Regressão: 21 suítes verdes (v1–v23) +
verificar_tudo 49✓/0✗. Gráfico: graficos/v23/v23_evidencias.png.