# KHTST_RUST v0.6.0 — Verificador NCM + Treino Conjunto + MoEs Redirecionáveis + Autoajuste

> **v0.6.0 (este ciclo)**: **verificador NCM calibrado** substitui o oráculo
> do Pensamento (V-1..V-4 — soundness sem acesso ao alvo), **treino conjunto
> Pensamento↔backbone** (fase C: gradiente bidirecional, PCGrad, acoplador
> duplex AC-1..AC-3), **MoEs de codificação/decodificação redirecionáveis com
> Mecanismo de Atenção próprio independente** para as variantes JEPA e SOM
> (M-R1..M-R5), e **autoajuste por telemetria** de todos os hiperparâmetros
> do Pensamento (A-1..A-5) com **seleção de arquitetura por UCB1** e loop
> iterativo com parada marginal. Provas: `docs/memorias/r-23…r-27`.
> Veredito consolidado: **46/46 gates verdes** (script 59) + **54/54 testes
> cargo**.

Refatoração completa do projeto **KHTST** (`PowerMachine/khtst-multimodal-ptbr`) para **Rust** via **PyO3**, integrando o paradigma **NCM (Next-Concept Modeling)** com todas as provas matemáticas da coleção `memoria-ncm-khtst`, ADBA (atenção adaptativa no processamento paralelo) e Ponte Duplex (comunicação bidirecional simultânea entre modelos).

## O que é

- **Tokenizador de conceitos** (Estágio A): VQ-VAE residual multiscale com codebooks **Stiefel/RCO** e quantização **GSQ** (Gumbel-Softmax com gradiente exato) — contração geométrica (1−1/K) por nível (Teo A.1/D.4), nested dropout (prefixos anytime, Teo A.2).
- **Gerador next-concept** (Estágio B): fatoração `p(c) = Π_ℓ p(c_ℓ|c_{<ℓ})` com predição **paralela** intra-nível — **MLE exato sem ELBO** (Teo B.1), **NFE = L** (7 ≪ 256; Teo B.2), corrupção de condicionamento como DRO (Teo C.3), MTP ⊂ NCM (Teo D.6), PCGrad (Teo D.7).
- **Tronco híbrido 5:1**: 5 camadas **ADBA** + 1 slot **Mamba-3 SSD** (scan diagonal com adjunto exato) — máscara block-causal com 0 vazamentos (Teo D.1, V4).
- **Ponte Duplex**: A↔B com canais limitados, rodadas com timeout — sem deadlock estrutural (Teo P.1), direções simultâneas medidas (P.2).
- **Telemetria completa**: séries JSONL, escore de aprendizado, **ajuste automático auditado** de LR/clip/ε/λ/τ **+ τ_c/B/N/g do Pensamento e arquitetura (UCB1)**, painel polaridade-aware, diagnóstico typo-first.

## Novidades v0.6.0

- **Verificador NCM** (`verificador.rs`): o validador do Pensamento passa a ser a **própria confiança do NCM, calibrada** — temperatura por golden-section em log-T (V-1: minimiza KL na família), soundness `P(erro|aceito) ≤ 1−τ_c+ECE` **sem oráculo** (V-2), limiar por quantil DKW (V-3), entropia na forma estável `logsumexp−Σpz` (V-4). Fecha o débito r-21 §3.1.
- **Treino conjunto fase C** (`treino.rs::treinar_fase_c`): ajuste fino Pensamento↔backbone a partir do checkpoint da fase B — gatilho por confiança calibrada, correção δ injetada no condicionamento com gradiente **nos dois sentidos** (C-1), neutralidade residual (C-2), PCGrad com taxa de conflito medida (C-3), causalidade estrita (C-4), custo 4·fwd+2·bwd/passo (C-5). **AcopladorDuplo** (`acoplador.rs`): protocolo duplex lag-1 síncrono sobre a PonteDupla — causal por filtração (AC-1), sem deadlock (AC-2), consistência valor↔grafo (AC-3). Fecha o débito r-21 §3.3.
- **MoEs redirecionáveis com atenção própria** (`moe_redirecionavel.rs`): especialistas com papel Codificador/Decodificador **redirecionável por permutação em tempo de execução** (M-R1 invariância, M-R4 fechamento da classe), **Atenção própria independente da ADBA** com gate nascendo em 0 (M-R2 neutralidade + Lipschitz), passadas cod/dec **paralelas em 2 threads** com determinismo bit-a-bit (M-R3), alocação **water-filling por QE** — Cauchy–Schwarz (M-R5). Aplicações: **JEPA** (ablação 3 braços: pequena/densa/moe — o roteamento ganha 45% da capacidade equiparada) e **SOM 4D** (refinamento residual QE −73% + redirecionamento p/ decodificador 17× melhor).
- **Autoajuste por telemetria** (`controlador.rs`): τ_c por quantil DKW (A-1), orçamento B por análise marginal com ρ̂ mediano (A-2), N por Hoeffding + **lema do acordo par-a-par** `p̂=(1+√(2a−1))/2` (A-3), arquitetura por **UCB1** com arrependimento sublinear (A-4), gate g por Bernstein empírico com LCB (A-5) — **todo ajuste auditado com motivo**. Fecha o débito r-21 §3.5 + painel polaridade-aware (r-22 §7).
- **Loop iterativo de aprimoramento** (script 58): UCB1 escolhe a arquitetura → treina em dados reais → telemetria regula (Theil–Sen) → recompensa → parada marginal — vencedor `moe-e8-redirect` com **61,6% de perda preditiva menor** que o baseline, arrependimento 0,058, parada na rodada 11.

## Instalação

```bash
pip install khtst_rust-*.whl   # wheel abi3 (Python ≥ 3.10, manylinux)
# ou do fonte: maturin build --release && pip install target/wheels/*.whl
```

## Uso rápido

```python
import khtst_rust as K

cfg = K.Config("configs/base_rust.json")          # valida + orçamento de cache
bpe = K.Bpe.treinar(textos, 16384)                # BPE byte-level próprio

# Fase A: tokenizador (nested dropout + GSQ/RCO Stiefel)
K.treinar_fase_a(cfg, sequencias, caminho_telemetria="tel_a.jsonl",
                 caminho_checkpoint="tokenizador.json", teto_seg=430)

# Fase B: gerador (MLE exato + κ + MTP + JEPA + PCGrad)
K.treinar_fase_b(cfg, sequencias, "tokenizador.json",
                 caminho_telemetria="tel_b.jsonl",
                 caminho_checkpoint="gerador.json", teto_seg=330)

# NOVO — Fase C: treino conjunto Pensamento↔backbone (verificador NCM,
# acoplador duplex, autoajuste A-1..A5; ajuste fino a partir da fase B)
K.treinar_fase_c(cfg, sequencias, "tokenizador.json", passos=240,
                 caminho_gerador="gerador.json",
                 caminho_telemetria="tel_c.jsonl", teto_seg=540)

# NOVO — verificador NCM isolado (calibração + soundness sem oráculo)
v = K.calibrar_verificador(logits_retidos, alvos, epsilon=0.25)

# NOVO — MoE redirecionável (provas M-R1..M-R5; dados reais)
K.demo_moe_redirecionavel(d=16, n=96, semente=42)
K.jepa_com_moe(patches, "moe", passos=90, frac_mascara=0.45, semente=7)
K.som_com_moe(dados_f64, lado=2, passos=90, semente=42)

# NOVO — ciclo d com verificador NCM (produção, sem oráculo)
K.demo_pensamento_ncm(d_cond=12, d_saida=6, n_tentativas=5,
                      passos_treino=220, limiar_conf=0.92, orcamento=6, semente=42)
```

## Estrutura

```
src/            26 módulos Rust (ver docs/memorias/r-02 + r-27 §1)
configs/        base_rust.json (espelho do base.json v23 + seção ncm)
scripts/        39-42 (dados/treino/teste/publicar v0.4) · 48-54 (v0.5) ·
                55-60 (v0.6: verificador, fase C, MoE, autoajuste, suíte, publicar)
docs/memorias/  r-01..r-07 + r-18..r-22 (v0.4/v0.5) + r-23..r-27 (v0.6)
resultados/     telemetria JSONL, suítes V/v050/v060, resumos de treino
```

## Verificações

- **54/54 testes cargo** (adjuntos vs. diferenças finitas; provas V/M-R/A em teste; integração SOM-MoE)
- **Suíte V legada**: 7/7 bloqueadoras verdes (V0,V1,V4,V9,V10,V13,V14) + V5b
- **Suítes v0.6.0**: verificador 11/11 · fase C real 9/9 · MoE/SOM/acoplador 14/14 · loop iterativo 11/11 → **consolidado 46/46 (script 59)**
- **Treino real** (Wikipédia PT-BR, streaming controlado): fase A perda 9,84→8,05, δ_ort 9,1e-7, codebook 53/64; fase B CE 4,15→3,97; **fase C CE 3,80→3,76 (mesmo lote), confiança 0,042→0,049, 211 rodadas duplex/0 timeouts**; JEPA-MoE 0,059 vs densa 0,107 vs pequena 0,129; SOM QE 0,334→0,089 (−73%); loop UCB1 gap 61,6%

## Provas e teoria

Toda a fundamentação matemática (20 teoremas + 10 corolários da integração NCM×KHTST; R.1–R.3 ADBA; P.1–P.3 ponte duplex; T-P1..T-P7 Pensamento; S4/T/G/H SOM; J/SM/R JEPA; **V-1..V-4 verificador; C-1..C-5 + AC-1..AC-3 treino conjunto; M-R1..M-R5 MoE redirecionável; A-1..A-5 autoajuste**) está em `docs/memorias/` com rastreabilidade teorema→código→verificação (r-03, r-27 §3).

## Convenções herdadas do projeto

Teoremas numerados com ∎ · nascimento neutro (opt-in) · leitura honesta (wall-clock como medido, ganhos não declaráveis por ΔCE curto) · tetos de arquivo/RAM · RNG dedicado para pareamento A/B · token HF apenas em variável de ambiente, apagado após uso · execução em primeiro plano (o fundo pode matar processos sem erro/OOM).

## Licença

Apache-2.0