KHTST v19 — acoplamento JEPA↔encoders de produção (vistas de tokens com pesos compartilhados, gradiente exato no encoder real Teo 31.2, conselho renormalizado 31.3, alvo EMA pós-step com guarda 31.6) + SonicMoE no tronco opt-in (dispatch agrupado+tiles, equivalência sônico≡vetorial Δy≤7.1e-8 Teo 31.4, roofline honesto 31.5, pilha evitada 2.21MB/forward) + A/B/C PAREADO em dados reais 1015 registros com pareamento exato por RNG dedicado (Teo 31.7; ΔCE monótono em λ; JEPA acoplada −74%) + doc 31 (Teos 31.1–31.7) + suíte v19 34/34 + regressão v1–v18 zero; sem estados de treino; sem segredos

.gitattributes

@@ -49,3 +49,4 @@ src/khtst/acelerado/mc_jepa.cpython-312-x86_64-linux-gnu.so filter=lfs diff=lfs
 src/khtst/acelerado/rco_gsq.cpython-312-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text
 src/khtst/treino/__pycache__/treinador.cpython-312.pyc filter=lfs diff=lfs merge=lfs -text
 src/khtst/ipc/khtst_ipc.cpython-312-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text
+graficos/v19/v19_evidencias.png filter=lfs diff=lfs merge=lfs -text

PLANO_KHMAMBAJEPA.md

@@ -25,7 +25,7 @@ de parâmetros no treino E na inferência.
 - Memória: SOM/GSOM/janela 1M indexada; difusão com motor de sonho
   (ciclo fechado, v15.1).
 
-## 2. Estado por subsistema (v17)
+## 2. Estado por subsistema (v19)
 
 | Subsistema | Estado | Prova/evidência |
 |---|---|---|
@@ -45,19 +45,22 @@ de parâmetros no treino E na inferência.
 | **λ_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) |
+| **SonicMoE (IO/tile-aware)** | ✅ v18+v19 | doc 30 Teo 30.13 (módulo); doc 31 Teos 31.4/31.5 (tronco opt-in, equivalência Δy≤7.1e-8, pilha 2.21MB/forward) |
+| **ReplaySSM** | ✅ v18 | doc 30 Teo 30.14; reservoir uniforme Monte-Carlo |
+| **Image-JEPA/V-JEPA 2 ACOPLADAS aos encoders de produção** | ✅ v19 | doc 31 Teos 31.2/31.6; vistas de tokens compartilham pesos; perda −74% (96 passos reais) |
+| **Audio-JEPA acoplada** (vista log-mel/convs) | ✅ v19 | doc 31 §3; 0.847→0.215 (−75%); Point/3D seguem no Mamba-3VL (§5) |
 | Brain-JEPA (fMRI/EEG) | ⏳ parcial | guarda do passo pronta (Teo 28.10); falta dataset |
-| T-JEPA / LeJEPA / BJEPA | ⏳ planejado §5 | — |
+| T-JEPA / LeJEPA / BJEPA | ✅ v18 (standalone) / ⏳ acopladas | texto permanece no MotorJepa do tronco (doc 31 §1); iso/ciclo prontos |
 | **v18 · robustez** | clamps Mamba-3 (δ,A), Muon wd 1e-4, NS fp32 adaptativo, PCGrad normalizado por EMA, τ GSQ 0.5/400 | Teos 30.2–30.6; regressão v1–v17 zero |
 | **v18 · lógica** | validar_config (Teo 30.7), telemetria com níveis+rotação+histórico limitado (Teo 30.8), treinador em 4 mixins+facade | suíte v17 56✓ pós-refatoração |
 | **v18 · IPC** | khtst/ipc: Rust (fonte) + Cython (produção, atomics C11) + fallback; 2 rings SPSC bidirecionais, SCM_RIGHTS, CRC32 | Teos 30.9/30.10; demo 2 processos 64 frames eco OK |
 | **v18 · família JEPA** | 10 variantes (Image/V2/MC/Audio/Point/3D/Brain/T/Le/BJEPA) + ConselhoJepas multimodal | Teos 30.11/30.12; treino 5 passos L 1.19→0.82 |
 | **v18 · SonicMoE/ReplaySSM** | dispatch agrupado+tiles+int8 com telemetria IO; reservoir de estados com re-injeção e drift | Teos 30.13/30.14; reservoir uniforme Monte-Carlo |
+| **v19 · acoplamento JEPA↔encoders** | vistas de tokens compartilham pesos dos encoders REAIS; conselho renormalizado; alvo EMA pós-step com guarda | Teos 31.1–31.3/31.6; gradiente exato no encoder (drift 8.3e-4 > 7.0e-4); perda −74% |
+| **v19 · SonicMoE no tronco (opt-in)** | forward_sonico (dispatch agrupado + tiles + telemetria); gate fonte única | Teos 31.1/31.4/31.5; Δy ≤ 7.1e-8 em produção; pilha evitada 2.21 MB/forward; wallclock CPU 0.83–0.875× (honesto) |
+| **v19 · A/B/C pareado real** | 3 braços, 96 passos, corpus 1015 registros reais (395 frescos), pareamento por RNG dedicado | Teo 31.7; ΔCE monótono em λ (+0.090→+0.046); graficos/v19/v19_evidencias.png |
 
-## 3. Matemática central (índice dos docs 00–30)
+## 3. Matemática central (índice dos docs 00–31)
 
 - **00–13**: SOM e variantes, atenção mista/KV, W8A8, MoE, microunidades,
   escala por computo, janela 1M indexada.
@@ -141,7 +144,9 @@ hardware chinês (30.15) + regras R18.1–R18.10.
    Image/V2/MC/Audio/Point/3D/Brain/T/Le/BJEPA + ConselhoJepas com gating
    renormalizado e nascimento neutro; Teos 30.11/30.12; a integração das
    variantes aos ENCODERS de produção do modelo (CodificadorImagem etc.)
-   permanece como evolução v19):
+   permanece como evolução v20 — o ACOPLAMENTO das 3 modalidades
+   core (imagem/áudio/vídeo) foi ENTREGUE na v19 via vistas de tokens
+   compartilhadas; doc 31):
    - 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);
@@ -154,15 +159,21 @@ hardware chinês (30.15) + regras R18.1–R18.10.
      o hinge quando d_latente grande);
    - BJEPA (bimodal imagem↔texto com predição cruzada latente).
    Todas herdam a ponte Cython (mc_jepa.pyx) e a guarda anti-colapso.
-4. **v19 — Cython total dos hot-paths**: conv1d seletiva do Mamba-3 e
+4. **v19 ✓ — Acoplamento JEPA↔encoders + SonicMoE no tronco (ENTREGUE,
+   doc 31)**: vistas de tokens compartilhadas (Teo 31.2), conselho
+   renormalizado (31.3), equivalência sônica (31.4), roofline honesto
+   (31.5), guarda por variante (31.6), A/B/C pareado real (31.7) —
+   resultados no RELATORIO §18; SonicMoE tronco opt-in com leitura
+   honesta (IO 2.0× modelado, wallclock CPU 0.83–0.875×).
+5. **v20 — 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. **v20 — Integração da tabela v17 no treinador**: ligar
+6. **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. **v18 ✓ — Hardware chinês** (ENTREGUE: `jepa_familia/dispositivo.py` —
+7. **v18 ✓ — Hardware chinês** (ENTREGUE: `jepa_familia/dispositivo.py` —
    detecção NPU Ascend / MLU Cambricon / XPU / CUDA / MPS / CPU com
    prioridade NPU/MLU e degradação honesta; Teo 30.15; toda a família
    JEPA usa ops torch padrão → roda em todos os backends).
@@ -186,6 +197,20 @@ hardware chinês (30.15) + regras R18.1–R18.10.
   atualizados TODA versão; redundâncias removidas.
 ---
 
+## 6b. Verificação v19 (resumo executável)
+
+- Suíte v19 NOVA: **34/34 verdes** (Teos 31.1–31.7 citados em cada
+  verificação: gate bit-idêntico, equivalência sônica de saída/gradientes,
+  telemetria IO honesta, gradiente no encoder REAL, alvo EMA sem grad,
+  RuntimeError da guarda, RNG dedicado do pareamento, nascimento neutro,
+  config opt-in, doc 31 presente).
+- verificar_tudo: **49✓/0✗** (após sincronizar patches/jepa.py —
+  dessincronização pré-existente da v18 detectada pelo próprio hash).
+- Regressão v1–v18: TODA VERDE (25/36/✓/37/32/48/44/21/✓/✓/28/27/40/—/✓/
+  56/46).
+- A/B/C real (96 passos × 3 braços, corpus 1015 reais): ver RELATORIO §18
+  e graficos/v19/v19_evidencias.png.
+
 ## 7. Verificação v18 (resumo executável)
 
 - Regressão v1–v17: TODA VERDE pós-refatoração (v1 25✓, v2 36✓, v3 ✓, v4 37✓,

README.md

@@ -95,6 +95,33 @@ gradiente**. Provas em `docs/matematica/27`.
 > --teto_horas 9.0 --continuar_ate_horas 8.0 --estados_hf`).
 
 
+## O que há de novo no v19 — ACOPLAMENTO JEPA↔ENCODERS DE PRODUÇÃO (A/B pareado) · SONICMOE NO TRONCO (opt-in) · DATASETS REAIS (provas em `docs/matematica/31`, memória em `PLANO_KHMAMBAJEPA.md`)
+
+- **JEPA acoplada aos encoders REAIS** (`jepa_familia/acoplamento.py`):
+  vistas de tokens que COMPARTILHAM os pesos de `CodificadorImagem/Audio/
+  Video` — o gradiente da auto-supervisão treina o encoder que o modelo
+  realmente usa (Teo 31.2 — regra da cadeia exata; sem gêmeo paralelo).
+  Alvo EMA pós-step com guarda de ordem por variante (Teo 31.6) e conselho
+  renormalizado com nascimento neutro (Teo 31.3). Opt-in:
+  `treino.jepa_acoplado.lambda` (default 0 — v18 exato, Teo 31.1).
+- **SonicMoE no TRONCO** (opt-in `modelo.sonicmoe.ativo`): execução com
+  dispatch agrupado por expert + GEMM em tiles + telemetria IO; gate é
+  fonte única (`_computar_gate`) — equivalência provada e medida
+  (Teo 31.4: Δy ≤ 7.1e-8 em produção, Δgrad ≤ 2.1e-7, gate bit-idêntico);
+  roofline HONESTO (Teo 31.5): ganho de IO de pesos (pilha evitada
+  2.21 MB/forward, 2.0× modelado) — wallclock CPU nesta escala 0.83–0.875×
+  (reportado como está).
+- **A/B/C PAREADO em dados reais** (Teo 31.7): 3 braços × 96 passos,
+  corpus REAL de 1015 registros (395 frescos de LeRobot/GSM8K/MATH-500/
+  hendrycks/OpenR1/IFM), pareamento EXATO por re-seed pós-construção +
+  gerador dedicado nas máscaras + conselho em eval. Resultados: baseline
+  1.606× · v19 λ=0.3 1.545× (ΔCE +0.090) · v19 λ=0.1 1.573× (ΔCE +0.046)
+  — monótono em λ (Cor. 31.7); JEPA acoplada APRENDE (perda −74%);
+  encoders recebem o gradiente extra (drift 8.3e-4 vs 7.0e-4).
+- **Verificação**: suíte v19 34/34 verdes · verificar_tudo 49✓/0✗ ·
+  regressão v1–v18 TODA VERDE · evidências em
+  `graficos/v19/v19_evidencias.png` e `telemetria_out/v19_relatorio_ab.json`.
+
 ## O que há de novo no v18 — ROBUSTEZ · IPC MODELO→MODELO · FAMÍLIA JEPA + SONICMOE + REPLAYSSM (provas em `docs/matematica/30`, memória em `PLANO_KHMAMBAJEPA.md`)
 
 - **Robustez provada (doc 30, Teos 30.1–30.6)**: clamps de sanidade no
@@ -273,6 +300,9 @@ imagem_caption · asr · traducao · raciocinio · classificacao`
 
 ## Histórico
 
+- **v19** — acoplamento JEPA↔encoders de produção com A/B/C pareado
+  (Teos 31.1–31.7), SonicMoE no tronco opt-in com equivalência provada,
+  dados reais 1015 registros; suíte v19 34/34, regressão zero.
 - **v18** — robustez provada (Teos 30.1–30.8), IPC Modelo→Modelo
   Rust/Cython (Teos 30.9–30.10), família JEPA 10 variantes + SonicMoE +
   ReplaySSM + hardware chinês (Teos 30.11–30.15); suíte v18 46/46,

RELATORIO_KHTST.md

@@ -965,3 +965,73 @@ ReplaySSM em hardware chinês/CPU, plano Markdown com provas e memória .md.
 **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).

configs/base.json

@@ -83,6 +83,10 @@
       "lambda_mamba3": 0.25,
       "ativo_vl": true,
       "n_camadas_vl": 6
+    },
+    "sonicmoe": {
+      "ativo": false,
+      "tile_m": 64
     }
   },
   "treino": {
@@ -198,6 +202,19 @@
       "alpha": 1.0,
       "eta": 0.05,
       "tau_kd": 2.0
+    },
+    "jepa_acoplado": {
+      "lambda": 0.0,
+      "variantes": [
+        "imagem",
+        "audio",
+        "video"
+      ],
+      "ema_momentum": 0.996,
+      "peso_var": 0.01,
+      "peso_iso": 0.0,
+      "pred_hidden": 256,
+      "aprende_gate": false
     }
   },
   "ciclo": {

docs/matematica/31-v19-acoplamento-jepa-sonicmoe.md

@@ -0,0 +1,269 @@
+# 31 — v19: Acoplamento JEPA↔Encoders de Produção e SonicMoE no Tronco
+
+**KHMAMBAJEPA — rodada v19** (requisito: "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").
+
+Fontes: `src/khtst/jepa_familia/acoplamento.py` (novo),
+`src/khtst/percepcao/moe.py` (gate extraído + `forward_sonico`),
+`src/khtst/treino/treinador.py` (integração), `src/khtst/config.py` +
+`configs/base.json` (chaves opt-in), `scripts/24_teste_v19.py` (A/B/C real).
+Suíte: `tests/test_khtst_v19.py`.
+
+Regras operacionais: R19.1–R19.8 (§8).
+
+---
+
+## 1. Problema e arquitetura (§2 do requisito)
+
+Na v18 a família JEPA (10 variantes) tinha STEMS PRÓPRIOS (convs pequenos): a
+auto-supervisão treinava esses stems paralelos, não os encoders que o modelo
+realmente usa (`CodificadorImagem/Audio/Video`). A v19 fecha o laço: cada
+variante acoplada consome uma **VISTA DE TOKENS** do encoder de produção
+compartilhando os pesos — o gradiente JEPA flui **para o encoder real**.
+
+```
+online:  z = Backbone_j(vista_j(θ_enc, x))      ← usa os MÓDULOS do encoder
+alvo:    z̃ = Backbone_j(vista_j(θ̃_enc, x))     ← deepcopy EMA (sem grad)
+perda:   L = MSE(P(z_ctx), sg(z̃_tgt)) + β·hinge_var + γ·iso
+```
+
+## 2. Teo 31.1 (nascimento neutro do acoplamento e do SonicMoE)
+
+**Afirmação.** Com `treino.jepa_acoplado.lambda = 0` (ou chave ausente) e
+`modelo.sonicmoe.ativo = false` (ou chave ausente), a trajetória de treino é
+a v18 EXATA: nenhum parâmetro novo, nenhum termo de perda novo, nenhum
+consumo de RNG novo.
+
+**Prova.** Construtiva, por inspeção do fluxo:
+(i) o conselho só é construído sob `float(cfg_jac.get("lambda",0)) > 0`
+(treinador, bloco v19) — com λ=0, `conselho_acoplado is None` ⟹ zero
+parâmetros novos no otimizador (`params_jac=[]`), zero termos em
+`auxiliares` (o ramo `if self.conselho_acoplado is not None` não dispara) e
+zero chamadas de `passo_pos_backward`. (ii) `KHTSTModel.__init__` só liga
+`modo_sonico` sob `cfg_sonic.get("ativo")` — sem a chave, `MoEAgrupavel
+.modo_sonico=False` (valor no `__init__`) e `forward` segue o caminho
+vetorial v8 linha a linha. (iii) A extração do gate para
+`_computar_gate` é refatoração VERBATIM (mesmas operações, mesma ordem —
+diff de código): com os mesmos pesos, o gate é bit-idêntico (medido:
+Δg=0.000e+00 na suíte v19). ∎
+
+**Verificação empírica**: suíte v19 (gate bit-idêntico; `sonicmoe_ativo
+is False` por padrão); regressão v1–v18 toda verde (o refator não mudou
+nada na prática do caminho antigo).
+
+## 3. Teo 31.2 (gradiente do acoplamento é o gradiente exato do encoder)
+
+**Afirmação.** Seja `vista_j(θ_enc, ·)` a vista que chama os módulos do
+encoder de produção (sem cópia). Então para qualquer perda L que dependa de
+θ_enc apenas via `z = Backbone(vista(θ_enc, x))`:
+
+    ∂L/∂θ_enc  =  (∂z/∂vista) · (∂vista/∂θ_enc)   — regra da cadeia EXATA,
+
+ou seja, a perda JEPA treina os MESMOS parâmetros que a perda CE (via
+prefixo multimodal); os dois gradientes somam-se no otimizador
+(PCGrad resolve conflitos — Teo 10.10/30.3).
+
+**Prova.** `vista_j` é um `nn.Module` cujo `forward` chama
+`self.enc.proj/blocos/bigru/norm` — módulos REFERENCIADOS (não copiados), e
+PyTorch autografa por identidade de `Tensor`, não por caminho de chamada.
+Portanto o grafo da perda JEPA contém os nós das operações aplicadas aos
+tensores de θ_enc, e o autograd acumula em `θ_enc.grad` a contribuição
+exata da cadeia acima. Como `θ_enc` também está no grafo da CE (encoder
+alimenta o prefixo), os dois termos acumulam no mesmo `.grad` — linearidade
+do gradiente. **Cor (31.2-cor, bug de integração evitado por construção):**
+os parâmetros do encoder NÃO podem ir ao grupo `extra_adam` do otimizador —
+eles já pertencem aos grupos principais; registrá-los duas vezes aplicaria
+dois passos ao mesmo θ. A integração filtra `id(p) ∉ id(modelo.parameters())`
+e só envia os parâmetros NOVOS (backbones/predictors/gate do conselho). ∎
+
+**Verificação empírica** (suíte v19): `perda` do conselho com lote de imagem
+produz `enc_imagem.proj.weight.grad ≠ 0`; alvo EMA com
+`requires_grad=False` para todos os parâmetros; treino real (96 passos,
+corpus de 1015 registros): drift do encoder com JEPA (8.26e-4) > drift sem
+(7.04e-4) — gradiente adicional REAL chegando ao encoder.
+
+**Corolário 31.2-a (bias EMA).** O alvo é θ̃_t = EMA(θ) com m=0.996; o
+gradiente do predictor vê um alvo "quase-estacionário": o viés relativo é
+O((1−m)·η·G) por passo (mesma análise do Teo 30.1) — controlado pela guarda
+de ordem (Teo 31.6).
+
+## 4. Teo 31.3 (conselho renormalizado é média convexa com nascimento neutro)
+
+**Afirmação.** A perda do conselho
+`L = Σ_m w_m·L_m / Σ_m w_m` (renormalização sobre as modalidades presentes)
+é média CONVEXA das perdas das variantes ativas, com w_m = softmax(logits)
+— no nascimento, w_m = 1/M (logits zero).
+
+**Prova.** softmax é positivo e soma 1; a renormalização sobre o
+subconjunto ativo A preserva `Σ_{m∈A} w'_m = 1` com w'_m ≥ 0 — média
+convexa ⟹ L entre min L_m e max L_m (nunca amplifica); gradiente:
+∂L/∂L_m = w'_m (pesos de contribuição exatos). Com logits zerados,
+w_m = 1/M ⟹ nascimento neutro (Teo 21.12 reusado). ∎
+
+## 5. SonicMoE no tronco (Teos 31.4–31.5)
+
+### Teo 31.4 (equivalência sônico ≡ vetorial)
+
+**Afirmação.** Para o MESMO gate `g` (mesma semente, mesmos pesos) e fase
+foco, o caminho `forward_sonico` produz
+
+    y_sonico[t] = (Σ_e g_e[t]·FFN_e(x_t)) / Σ_e g_e[t]  =  y_vetorial[t]
+
+com desvio apenas de ordem de acumulação em ponto flutuante; o MESMO vale
+para os gradientes em relação a x e a todos os pesos de expert, e para a
+telemetria (`_Z_ultimo`, `_g_ultimo`, L_lb, L_ort).
+
+**Prova.** (i) Gate: ambas as rotas chamam `_computar_gate` (fonte única;
+extração verbatim — Teo 31.1) ⟹ g bit-idêntico. (ii) Suporte: no caminho
+vetorial, `idx_at = {e : ∃t g_e[t]>0}` e `YE` é computado para (e,t) com
+g_e[t] possivelmente nulo; a soma final multiplica por g_e[t], então termos
+nulos não contribuem. O caminho sônico computa exatamente os pares com
+g_e[t]>0 (`linhas = (cols>0)`). Como o gate foco é softmax sobre os ativos
+(g_e[t]>0 ESTRITAMENTE para todo t e todo e ativo), os conjuntos de pares
+computados COINCIDEM (Σ_e n_e = A·BT — leitura honesta do modelo de custo,
+Teo 31.5-nota). (iii) FFN: `_ffn_tiles` computa
+`FFN(x) = Σ_c (silu(x·wg_cᵀ) ⊙ (x·wu_cᵀ))·wd_cᵀ` — particionamento do
+hidden: `h = silu(x·wgᵀ) ⊙ (x·wuᵀ)` exatamente, e a saída
+`h·wdᵀ = Σ_c h_c·wd_cᵀ` (linearidade da partição colunar de wd). A única
+diferença é a ordem de acumulação (soma por blocos) — erro ≤ N_bloco·ε·‖h‖
+em fp32 (ε≈1.2e-7), medido: Δy=3e-8. (iv) Agregação: `index_add_` é a
+mesma soma ponderada do `torch.sum(w.T·YE)` (comutatividade — Teo 19.11
+reusado); a normalização `soma_at` é idêntica. (v) Gradientes: autograd
+diferencia index_select/index_add_/linear exatamente; os termos que o
+vetorial calculava com peso zero tinham gradiente NULO e são omitidos —
+∂L/∂θ_e = Σ_t g_e[t]·δ_t·(∂FFN_e/∂θ) coincide. L_lb é função só de g
+(idêntica, Δ=0); L_ort e _Z_ultimo são reconstruídos com os MESMOS
+estimadores (médias por expert sobre as linhas ativas). ∎
+
+**Verificação empírica** (suíte v19 + treino real):
+Δy=3.0e-08, Δgrad_x=3.4e-08, Δgrad_w=2.1e-07, Δg=0, ΔL_lb=0, ΔL_ort=7.9e-08;
+em produção (braços B/C): Δy ≤ 7.1e-08.
+
+### Teo 31.5 (roofline HONESTO do ganho)
+
+**Afirmação.** Neste código o ganho do caminho sônico NÃO é redução de
+linhas de GEMM (o gate foco é softmax sobre todos os ativos ⟹ fator de
+trabalho = 1). O ganho é de IO de PESOS e localidade:
+
+1. **Pilha evitada**: o caminho vetorial materializa
+   `torch.stack(w_gate/w_up/w_down)` de A experts — cópia de
+   S = A·3·d_ff·d·4 bytes por forward (escrita + leitura); o sônico lê os
+   pesos de cada expert UMA vez, sem cópia.
+2. **YE em bloco evitado**: o vetorial materializa YE (A, BT, d) de uma
+   vez; o sônico materializa por grupo (mesma soma de elementos, pico de
+   memória menor).
+3. **Tiles**: com tile_m < d_ff, o bloco de linhas do peso fica na cache
+   e é reusado pelas linhas do grupo (localidade — efeito medido por
+   wall-clock, não afirmado analiticamente).
+
+**Prova.** Contagem de bytes: vetorial escreve a pilha (S bytes) e a lê na
+GEMM (S); sônico lê os pesos originais (S). YE: A·BT·d·4 em ambos (somatório
+dos grupos = YE). Logo a economia modelada é ≥ S por forward (escrita da
+pilha) — ganho_io = (2S + 2·YE)/(S + YE_grupo) ≈ 2 quando S ≳ YE. **Honesti-
+dade:** o wall-clock CPU medido no A/B (2 camadas, d=192, d_ff=160, BT=128)
+foi 0.83–0.875× (sônico ~14% MAIS LENTO) — em GEMMs pequenos o overhead do
+laço Python/index_select domina a economia de cópia; a arquitetura sônica é
+projetada para GEMMs maiores (GPU/NPU — onde a pilha evitada e a localidade
+dominam). NADA afirmamos além do medido. ∎
+
+**Nota (31.5-nota).** Se um futuro gate tornar-se esparso POR TOKEN
+(top-k com zeros), o mesmo código passa a omitir linhas automaticamente
+(`linhas = (cols>0)`) — o fator_trabalho deixaria de ser 1 sem mudança
+alguma aqui; a telemetria já mede isso.
+
+## 6. Teo 31.6 (guarda de ordem EMA por variante)
+
+**Afirmação.** Cada `NucleoJepa` acoplado mantém `_passos_sem_ema`; se mais
+de `tolerancia_ema + 1` chamadas de `perda()` ocorrerem sem
+`passo_pos_backward()`, um `RuntimeError` é lançado. No conselho,
+`tolerancia_ema = lote_efetivo` e `passo_pos_backward()` é chamado APÓS
+`optimizer.step()` no micro-final (mesmo contrato do MotorJepa).
+
+**Prova.** O viés do alvo por passo atrasado é O((1−m)·η·G) (Teo 30.1);
+exceder a tolerância significa que o alvo está atrasado ≥ lote_efetivo+1
+passos — a violação vira erro IMEDIATO em vez de viés silencioso. A ordem
+pós-step garante que a EMA absorve o θ APÓS o passo (alvo quase-estacioná-
+rio; Teo 5.2/30.1). No treino real 96 passos: o contador nunca violou
+(0 RuntimeErrors) e o alvo seguiu (drift EMA 6.7e-4 ≈ drift do encoder
+8.3e-4 × (1−m)·passos). ∎
+
+## 7. Teo 31.7 (A/B pareado exato)
+
+**Afirmação.** Com (i) re-seed APÓS a construção de modelo+treinador nos
+dois braços, (ii) perda JEPA usando gerador DEDICADO (`self._ger`) para as
+máscaras, (iii) conselho em modo `eval()` (sem dropout) e (iv) nenhuma
+outra operação de RNG no caminho JEPA, os dois braços consomem a MESMA
+sequência do RNG global ⟹ mesmos lotes na mesma ordem ⟹ ΔCE_t = CE_B(t) −
+CE_A(t) é pareado por passo.
+
+**Prova.** O estado do RNG global determina a escolha de tarefa e o
+montar-lote (mesmos códigos); as únicas operações de RNG novas no braço B
+seriam as máscaras da JEPA e o dropout dos backbones — (ii) desvia as
+máscaras para `torch.Generator` dedicado (semeado por variante) e (iii)
+desliga dropout; logo o fluxo global de B é idêntico ao de A por indução
+sobre os passos. (A construção do conselho consome RNG de init, mas ANTES
+do re-seed pós-construção.) Com lotes idênticos, as diferenças de CE são
+atribuíveis ÀS INTERVENÇÕES (λ, SonicMoE), não ao ruído entre braços —
+variância do estimador pareada ≤ variância de dois-runas independentes
+(Var[X−Y] = Var[X]+Var[Y]−2Cov[X,Y] e Cov>0 sob dados comuns). ∎
+
+**Corolário (honestidade do λ).** Sob conflito CE×JEPA, o ΔCE pareado é
+monótono em λ (Teo 28.7-ii reusada: a razão auxiliar/CE governa o desvio).
+Medido (96 passos, corpus real 1015): ΔCE(B, λ=0.3) = +0.0900;
+ΔCE(C, λ=0.1) = +0.0464 — monótono decrescente em λ, como prescrito; a
+perda JEPA cai 74% em ambos (0.808→0.205; 0.847→0.215) — as representações
+APRENDEM nos dois regimes.
+
+## 8. Regras operacionais
+
+- **R19.1 (opt-in).** `treino.jepa_acoplado.lambda > 0` liga o conselho;
+  `modelo.sonicmoe.ativo` liga o caminho sônico. Padrões em
+  `configs/base.json` DESLIGADOS (nascimento neutro, Teo 31.1).
+- **R19.2 (parâmetros novos apenas).** NUNCA registrar parâmetros do
+  encoder em dois grupos do otimizador (Teo 31.2-cor) — o filtro por
+  identidade é obrigatório.
+- **R19.3 (ordem EMA).** `conselho.passo_pos_backward()` APÓS
+  `optimizer.step()` no micro-final; tolerância = lote_efetivo (Teo 31.6).
+- **R19.4 (λ calibrado).** Começar com λ=0.1 (razão auxiliar/CE ≤ 0.3 —
+  Teo 28.7-ii); medir ΔCE pareado antes de subir λ (Cor. 31.7).
+- **R19.5 (pareamento).** Para A/B pareado: re-seed pós-construção,
+  gerador dedicado nas máscaras, conselho em eval (Teo 31.7) — qualquer
+  novo consumidor de RNG no caminho JEPA quebra o pareamento.
+- **R19.6 (leitura honesta do SonicMoE).** O ganho garantido é de IO de
+  pesos (pilha evitada ≥ S/forward, Teo 31.5); wall-clock CPU em escala
+  pequena pode ser neutro/negativo (medido 0.83–0.875×) — reportar ambos.
+- **R19.7 (fase densa).** O caminho sônico só atua na fase FOCO; na densa
+  o vetorial mantém a máxima conexão (sem trabalho esparsível — Teo 31.5).
+- **R19.8 (variantes presentes).** O conselho omite variantes sem encoder
+  no modelo (nunca erro); o gating renormaliza sobre as ativas (Teo 31.3).
+
+## 9. Evidência empírica consolidada (96 passos, corpus real 1015 registros)
+
+| Braço | CE início→fim | melhoria | ΔCE pareado vs A | JEPA acoplada |
+|-------|---------------|----------|------------------|----------------|
+| A baseline_v18 | 9.738 → 6.064 | 1.606× | — | — |
+| B v19 λ=0.3 + SonicMoE | 9.726 → 6.296 | 1.545× | +0.0900 | 0.808 → 0.205 (−74%) |
+| C v19 λ=0.1 + SonicMoE | 9.732 → 6.187 | 1.573× | +0.0464 | 0.847 → 0.215 (−75%) |
+
+- Drift dos encoders de produção (gradiente JEPA+CE vs CE só):
+  imagem 8.26e-4 (B) / 8.75e-4 (C) vs 7.04e-4 (A); áudio 7.95e-4 / 7.97e-4
+  vs 6.59e-4 — o gradiente da auto-supervisão chega ao encoder REAL.
+- SonicMoE: equivalência Δy ≤ 7.1e-08 em produção; ganho IO modelado 2.0×
+  (pilha evitada 2.21 MB/forward); wallclock CPU 0.83–0.875× (honesto —
+  R19.6).
+- Dados reais: coleta FRESCA de 395 registros (LeRobot fetchman, GSM8K,
+  MATH-500, hendrycks, OpenR1, IFM socratic) mesclada ao corpus v16.
+- Protocolo: 96 passos × 3 braços com retomada por checkpoint (RAM 4 GiB);
+  pareamento por re-seed pós-construção + RNG dedicado (Teo 31.7).
+
+## 10. O que NÃO afirmamos
+
+- Que o wall-clock CPU do SonicMoE melhore nesta escala (não melhorou:
+  0.83–0.875×; o ganho garantido é de IO de pesos).
+- Que a CE de 96 passos BENEFICIE do acoplamento (não beneficiou ainda:
+  ΔCE ≤ +0.09 com λ≤0.3; benefícios de representação tipicamente aparecem
+  em corridas longas/probes downstream — requer corrida de 9 h).
+- Que o gate foco atual produza economia de linhas (fator_trabalho=1 —
+  softmax sobre ativos; a economia por esparsidade exigiria top-k por
+  token, mudança de semântica fora do escopo desta rodada).

patches/jepa.py

@@ -243,6 +243,16 @@ class MotorJepa(nn.Module):
         # correção D: janelas COM TETO (RAM limitada em treino de 9 h)
         self.historico = deque(maxlen=self.cfg.janela_telemetria)
         self._taxa_sucesso = deque(maxlen=self.cfg.janela_telemetria)
+        # v18 — GUARDA DE ORDEM EMA (requisito §1.1.1/§3.1, Teo 30.1):
+        # a atualização do alvo DEPENDE de passo_pos_backward() rodar APÓS
+        # optimizer.step(); qualquer refatoração do laço pode quebrar essa
+        # ordem SEM AVISO. O contador _passos_sem_ema conta perdas() desde
+        # a última atualização do alvo; exceder a tolerância (n de
+        # micro-passos por grupo do otimizador) LANÇA RuntimeError — a
+        # quebra vira erro IMEDIATO e rastreável, não viés silencioso.
+        self._passos_sem_ema = 0
+        self.tolerancia_micro = 1          # treinador ajusta = lote_efetivo
+        self._n_ema_atualizados = 0
 
     # -------- ganho de experiência: tabela de μ por episteme do EMA -------
     def tabela_mu(self, taxa_sucesso_ema: float) -> float:
@@ -265,7 +275,19 @@ class MotorJepa(nn.Module):
         return sum(self._taxa_sucesso) / len(self._taxa_sucesso)
 
     def perda(self, h: torch.Tensor, gerador=None) -> tuple[torch.Tensor, dict]:
-        """h: (B,T,d) saída do tronco. Devolve (perda, telemetria)."""
+        """h: (B,T,d) saída do tronco. Devolve (perda, telemetria).
+
+        v18 — guarda de ordem EMA (Teo 30.1): se mais de `tolerancia_micro`
+        chamadas ocorrerem sem `passo_pos_backward()` entre elas, o alvo
+        está enviesado e o erro é LANÇADO (requisito §1.1.1/§3.1).
+        """
+        self._passos_sem_ema += 1
+        if self._passos_sem_ema > max(1, int(self.tolerancia_micro)) + 1:
+            raise RuntimeError(
+                "EMA do JEPA fora de ordem: passo_pos_backward() não foi "
+                f"chamado após optimizer.step() há {self._passos_sem_ema - 1} "
+                "passos — alvo enviesado (doc 30, Teo 30.1; requisito "
+                "§1.1.1/§3.1). Corrija a ordem no laço de treino.")
         cfg = self.cfg
         B, T, _ = h.shape
         if T < 2:
@@ -334,6 +356,10 @@ class MotorJepa(nn.Module):
     def passo_pos_backward(self) -> float:
         """Atualiza o alvo com μ da tabela REAL. Chamar DEPOIS do
         optimizer.step() — se antes, o alvo enxerga um encoder já atualizado
-        e o EMA fica enviesado (ordem obrigatória, relatório §8.3)."""
+        e o EMA fica enviesado (ordem obrigatória, relatório §8.3).
+        v18: reinicia o contador da guarda de ordem (Teo 30.1)."""
         self.funil_bar.mu = self.tabela_mu(self.taxa_sucesso_media())
-        return self.funil_bar.atualizar(self.funil)
+        drift = self.funil_bar.atualizar(self.funil)
+        self._passos_sem_ema = 0
+        self._n_ema_atualizados += 1
+        return drift

scripts/24_teste_v19.py

@@ -0,0 +1,401 @@
+# -*- coding: utf-8 -*-
+"""24_teste_v19.py — TESTE REAL v19 (KHMAMBAJEPA, doc 31 §7).
+
+Requisitos do usuário atendidos aqui:
+  • "acoplar as variantes JEPA aos encoders de produção com A/B pareado" —
+    dois braços com MESMA semente e MESMOS lotes (pareamento exato: a perda
+    JEPA usa gerador dedicado + modo eval — não consome o RNG do treino);
+  • "ativar SonicMoE no tronco (opt-in)" — braço B com sonicmoe.ativo=true;
+    micro-benchmark foco sônico×vetorial (wall-clock + equivalência + IO);
+  • "rodar testes de datasets reais" — corpus REAL (LeRobot frames, GSM8K/
+    matemática, wikitext) + coleta FRESCA opcional com orçamento.
+
+Braços (UMA variante por processo — cada modelo completo):
+  A) baseline_v18     — jepa_acoplado λ=0, sonicmoe off (v18 EXATO)
+  B) v19_completo     — jepa_acoplado λ=0.3 (imagem+audio) + sonicmoe ON
+  C) v19_lambda_baixo — idêntico a B com λ=0.1 (prescrição Teo 28.7-ii:
+     razão auxiliar/CE ≤ 0.3 — o λ alto desvia capacidade da CE)
+
+Uso:
+  python3 scripts/24_teste_v19.py --coletar            # 1× (dados frescos)
+  python3 scripts/24_teste_v19.py --variante baseline_v18 --passos 140
+  python3 scripts/24_teste_v19.py --variante v19_completo   --passos 140
+  python3 scripts/24_teste_v19.py --variante v19_lambda_baixo --passos 96
+  python3 scripts/24_teste_v19.py --relatorio          # consolida o par
+"""
+from __future__ import annotations
+
+import argparse
+import base64
+import importlib.util
+import json
+import os
+import sys
+import time
+
+RAIZ = os.environ.get("KHTST_RAIZ", "/home/z/my-project/workspace/repo_src")
+sys.path.insert(0, os.path.join(RAIZ, "src"))
+
+CORPUS = os.path.join(RAIZ, "cache_dados", "corpus_v16.jsonl")
+TOKENIZADOR = os.path.join(RAIZ, "cache_dados", "tokenizador_v16.json")
+TOK_ANTIGO = os.path.join(RAIZ, "cache_dados", "tokenizador.json")
+TELEMETRIA = os.path.join(RAIZ, "telemetria_out")
+V19_SCRIPT = os.path.join(RAIZ, "scripts", "19_teste_v16.py")
+
+
+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 coletar_fresco() -> dict:
+    """Coleta FRESCA com orçamento (datasets reais; reusa o coletor v16)."""
+    spec = importlib.util.spec_from_file_location("teste_v16", V19_SCRIPT)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod.coletar(max_por_fonte=8, orcamento_s=50.0)
+
+
+def _estado_rng() -> dict:
+    import random
+    import numpy as np
+    import torch
+    return {"torch": torch.get_rng_state(),
+            "random": random.getstate(),
+            "numpy": np.random.get_state()}
+
+
+def _restaurar_rng(est: dict) -> None:
+    import random
+    import numpy as np
+    import torch
+    torch.set_rng_state(est["torch"])
+    random.setstate(est["random"])
+    np.random.set_state(est["numpy"])
+
+
+def rodar_variante(nome: str, v19: bool, passos: int, parte: int = 0,
+                   lambda_jac: float = 0.3) -> dict:
+    import gc
+    import random
+    import numpy as np
+    import torch
+    # CPU sandbox: limitar intraop threads (sem isto o env ignora OMP_NUM_
+    # THREADS herdado e o passo fica 2× mais lento por thrashing)
+    if not (torch.cuda.is_available() or torch.xpu.is_available()):
+        torch.set_num_threads(int(os.environ.get("OMP_NUM_THREADS", "2")))
+    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
+
+    SEED = 2026
+    cfg = Config()
+    cfg.dados.semente = SEED
+    cfg.treino.warmup = 8
+    cfg.treino.lote = 4
+    cfg.treino.lote_efetivo = 1          # protocolo v16 exato (RAM 4 GiB)
+    cfg.treino.qat_ultimos_passos = 0
+    cfg.treino.ensemble["a_cada"] = 24   # RF menos frequente (RAM)
+    cfg.modelo.escalacao["ativo"] = False
+    if v19:
+        # REQUISITO v19: JEPA ACOPLADA aos encoders de produção + SonicMoE
+        cfg.treino.jepa_acoplado["lambda"] = lambda_jac
+        cfg.treino.jepa_acoplado["variantes"] = ["imagem", "audio"]
+        cfg.treino.jepa_acoplado["pred_hidden"] = 256
+        cfg.modelo.sonicmoe["ativo"] = True
+        cfg.modelo.sonicmoe["tile_m"] = 32
+    else:
+        cfg.treino.jepa_acoplado["lambda"] = 0.0
+        cfg.modelo.sonicmoe["ativo"] = False
+
+    os.makedirs(TELEMETRIA, exist_ok=True)
+    hub = TelemetryHub(os.path.join(TELEMETRIA, f"treino_v19_{nome}.jsonl"))
+    tk = TokenizadorKHTST(TOKENIZADOR if os.path.exists(TOKENIZADOR)
+                          else TOK_ANTIGO)
+    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)
+    # PAREAMENTO EXATO (Teo 31.7): re-seed APÓS construir modelo+treinador
+    # (a construção consome RNG de init — os dois braços partem do MESMO
+    # estado aqui; a perda JEPA não consome o RNG global: gerador dedicado
+    # + eval). Braço A não tem conselho — o fluxo de lotes é idêntico.
+    _restaurar_rng(est_padrao(SEED))
+
+    # ---- retomada por PARTES (RAM sandbox: o processo morre entre chamadas;
+    # v19 salva TUDO que afeta o pareamento: pesos, otimizador, conselho,
+    # contagem de passos, perdas e os 3 estados de RNG)
+    ckpt = os.path.join(TELEMETRIA, f"ckpt_v19_{nome}.pt")
+    perdas: list[float] = []
+    tel_jepa_ac: list[dict] = []
+    passo_inicial = 0
+    if parte and os.path.exists(ckpt):
+        est = torch.load(ckpt, map_location="cpu", weights_only=False)
+        modelo.load_state_dict(est["modelo"])
+        treinar.otimizador.load_state_dict(est["otimizador"])
+        if treinar.conselho_acoplado is not None and est.get("conselho"):
+            treinar.conselho_acoplado.load_state_dict(est["conselho"])
+        treinar.passo_global = est["passo_global"]
+        perdas = est["perdas"]
+        tel_jepa_ac = est.get("tel_jepa_ac", [])
+        torch.set_rng_state(est["rng_torch"])
+        random.setstate(est["rng_py"])
+        np.random.set_state(est["rng_np"])
+        passo_inicial = est["passo_global"]
+        print(f"[retomada] passo_global={est['passo_global']} perdas={len(perdas)}",
+              flush=True)
+
+    # drift dos encoders de produção (medida de treino REAL dos encoders)
+    im0 = torch.zeros(0)
+    au0 = torch.zeros(0)
+    if getattr(modelo, "enc_imagem", None) is not None:
+        im0 = modelo.enc_imagem.proj.weight.data.detach().clone()
+    if getattr(modelo, "enc_audio", None) is not None:
+        au0 = modelo.enc_audio.conv1.weight.data.detach().clone()
+    if parte and os.path.exists(ckpt):
+        est = torch.load(ckpt, map_location="cpu", weights_only=False)
+        im0 = est["im0"]
+        au0 = est["au0"]
+
+    t0 = time.time()
+    alvo = min(passos, passo_inicial + parte) if parte else passos
+    while treinar.passo_global < alvo:
+        tp = time.time()
+        perda = treinar._passo()
+        if perda == perda:
+            perdas.append(perda)
+        if parte:
+            print(f"[passo {treinar.passo_global} {time.time()-tp:.1f}s "
+                  f"perda {perda:.3f}]", flush=True)
+        if treinar.conselho_acoplado is not None:
+            tel = getattr(treinar, "ultima_tel_jac", {})
+            if tel:
+                tel_jepa_ac.append(
+                    {k: (float(v) if torch.is_tensor(v) else v)
+                     for k, v in tel.items()
+                     if k in ("loss", "ativas", "imagem/loss", "imagem/mse",
+                              "audio/loss")})
+    tempo_s = time.time() - t0
+
+    if parte:
+        torch.save({"modelo": modelo.state_dict(),
+                    "otimizador": treinar.otimizador.state_dict(),
+                    "conselho": (treinar.conselho_acoplado.state_dict()
+                                 if treinar.conselho_acoplado is not None else None),
+                    "passo_global": treinar.passo_global,
+                    "perdas": perdas, "tel_jepa_ac": tel_jepa_ac,
+                    "rng_torch": torch.get_rng_state(),
+                    "rng_py": random.getstate(),
+                    "rng_np": np.random.get_state(),
+                    "im0": im0, "au0": au0}, ckpt)
+        if treinar.passo_global < passos:
+            return {"parcial": True, "passos": treinar.passo_global}
+
+    res = {
+        "variante": nome, "v19": v19, "passos": len(perdas),
+        "lote": cfg.treino.lote,
+        "perda_media_inicial": round(sum(perdas[:8]) / max(1, len(perdas[:8])), 4),
+        "perda_media_final": round(sum(perdas[-8:]) / max(1, len(perdas[-8:])), 4),
+        "perda_min": round(min(perdas), 4),
+        "perdas_finitas": all(p == p for p in perdas),
+        "tempo_s": round(tempo_s, 1),
+        "tempo_ms_por_passo": round(1000 * tempo_s / max(1, len(perdas)), 1),
+        "n_registros_corpus": len(registros),
+        "perdas_por_passo": perdas,
+    }
+    if getattr(modelo, "enc_imagem", None) is not None and im0.numel():
+        res["drift_encoder_imagem"] = float(
+            (modelo.enc_imagem.proj.weight.data - im0).abs().max())
+    if getattr(modelo, "enc_audio", None) is not None and au0.numel():
+        res["drift_encoder_audio"] = float(
+            (modelo.enc_audio.conv1.weight.data - au0).abs().max())
+
+    # ---- SONICMOE micro-benchmark (foco): sônico × vetorial, MESMOS pesos --
+    if v19:
+        import torch as _t
+        moes = [b.moe for b in modelo.blocos
+                if getattr(b, "moe", None) is not None]
+        if moes:
+            modelo.eval()
+            modelo.definir_fase_moe("foco")
+            # lote sintético do próprio espaço (h do tronco: (B,T,d))
+            B, T, d = 2, 32, int(cfg.modelo.d_modelo)
+            x = _t.randn(B, T, d)
+            # vetorial
+            for m in moes:
+                m.modo_sonico = False
+            _t.manual_seed(SEED)
+            _t.cuda.manual_seed_all(SEED)
+            t0v = time.time()
+            ys = [m(x) for m in moes for _ in range(10)]
+            tv = (time.time() - t0v) / 10
+            # sônico (mesmos pesos)
+            for m in moes:
+                m.modo_sonico = True
+            _t.manual_seed(SEED)
+            _t.cuda.manual_seed_all(SEED)
+            t0s = time.time()
+            ysn = [m(x) for m in moes for _ in range(10)]
+            ts = (time.time() - t0s) / 10
+            dy = max(float((a - b).abs().max()) for a, b in zip(ys, ysn))
+            io = moes[0].ultimo_io
+            res["sonicmoe"] = {
+                "n_camadas": len(moes),
+                "tempo_vetorial_ms": round(1000 * tv, 2),
+                "tempo_sonico_ms": round(1000 * ts, 2),
+                "speedup_wallclock": round(tv / max(ts, 1e-9), 3),
+                "delta_y_max": dy,
+                "ganho_io_modelado": round(io.get("ganho_io", 0.0), 3),
+                "pilha_evitada_bytes": io.get("pilha_evitada_bytes", 0),
+                "fator_trabalho": round(io.get("fator_trabalho", 0.0), 3),
+                "tile_m": io.get("tile_m", 0)}
+            # conselho — curva da perda JEPA acoplada (aprendizado real)
+            if tel_jepa_ac:
+                ini = [t["loss"] for t in tel_jepa_ac[:8]]
+                fim = [t["loss"] for t in tel_jepa_ac[-8:]]
+                res["jepa_acoplada"] = {
+                    "passos_com_perda": len(tel_jepa_ac),
+                    "perda_inicial": round(sum(ini) / max(1, len(ini)), 4),
+                    "perda_final": round(sum(fim) / max(1, len(fim)), 4),
+                    "drift_alvo_ema_imagem": float((
+                        treinar.conselho_acoplado.variantes["imagem"]
+                        .target.stem.enc.proj.weight.data
+                        - treinar.conselho_acoplado.variantes["imagem"]
+                        .stem.enc.proj.weight.data).abs().max())
+                    if "imagem" in treinar.conselho_acoplado.variantes else None}
+
+    del treinar, modelo, orquestrador, hub
+    gc.collect()
+    return res
+
+
+def est_padrao(seed: int) -> dict:
+    """Estado RNG padrão reconstrutível (mesma semente nos dois braços)."""
+    import random
+    import numpy as np
+    import torch
+    torch.manual_seed(seed)
+    random.seed(seed)
+    np.random.seed(seed)
+    return {"torch": torch.get_rng_state(), "random": random.getstate(),
+            "numpy": np.random.get_state()}
+
+
+def relatorio() -> int:
+    braços = ["baseline_v18", "v19_completo", "v19_lambda_baixo"]
+    dados = {}
+    for nome in braços:
+        p = os.path.join(TELEMETRIA, f"v19_{nome}.json")
+        if os.path.exists(p):
+            with open(p) as f:
+                dados[nome] = json.load(f)
+    if "baseline_v18" not in dados or "v19_completo" not in dados:
+        print("faltam resultados dos braços A/B")
+        return 1
+    a = dados["baseline_v18"]
+    print("=== TESTE REAL v19 — A/B/C PAREADO (doc 31 §7) ===")
+    print(f"registros reais: {a['n_registros_corpus']} | passos: {a['passos']}"
+          f" | lote: {a['lote']}")
+    pa = a["perdas_por_passo"]
+    for nome, rotulo in (("baseline_v18", "A baseline_v18     "),
+                         ("v19_completo", "B v19_completo     "),
+                         ("v19_lambda_baixo", "C v19_lambda_baixo ")):
+        if nome not in dados:
+            continue
+        r = dados[nome]
+        print(f"{rotulo}: {r['perda_media_inicial']} → "
+              f"{r['perda_media_final']} ({r.get('melhoria_x', '—')}×)")
+        if nome != "baseline_v18":
+            pb = r["perdas_por_passo"]
+            n = min(len(pa), len(pb))
+            deltas = [pb[i] - pa[i] for i in range(n)]
+            half = n // 2
+            media = sum(deltas) / n
+            print(f"    ΔCE pareado vs A: {media:+.4f} | 1ª metade "
+                  f"{sum(deltas[:half]) / max(1, half):+.4f} | 2ª metade "
+                  f"{sum(deltas[half:]) / max(1, n - half):+.4f}")
+        if "jepa_acoplada" in r:
+            j = r["jepa_acoplada"]
+            print(f"    JEPA acoplada: {j['perda_inicial']} → {j['perda_final']}"
+                  f" | drift alvo EMA imagem {j['drift_alvo_ema_imagem']:.2e}")
+        if "sonicmoe" in r:
+            s = r["sonicmoe"]
+            print(f"    SonicMoE: Δy {s['delta_y_max']:.1e} | ganho_io "
+                  f"{s['ganho_io_modelado']}× | pilha evitada "
+                  f"{s['pilha_evitada_bytes'] / 1e6:.2f} MB/forward | "
+                  f"wallclock {s['speedup_wallclock']}× (CPU, escala pequena)")
+    for k in ("drift_encoder_imagem", "drift_encoder_audio"):
+        linha = " ".join(f"{nome.split('_')[-1]}={dados[nome].get(k, 0):.2e}"
+                         for nome in dados)
+        print(f"{k}: {linha}")
+    saida = {"braços": {n: {k: v for k, v in r.items()
+                            if k != "perdas_por_passo"}
+                        for n, r in dados.items()}}
+    with open(os.path.join(TELEMETRIA, "v19_relatorio_ab.json"), "w",
+              encoding="utf-8") as f:
+        json.dump(saida, f, ensure_ascii=False, indent=2)
+    print("salvo: telemetria_out/v19_relatorio_ab.json")
+    return 0
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--coletar", action="store_true")
+    ap.add_argument("--variante", choices=["baseline_v18", "v19_completo",
+                                           "v19_lambda_baixo"])
+    ap.add_argument("--passos", type=int, default=140)
+    ap.add_argument("--lambda_jac", type=float, default=0.3)
+    ap.add_argument("--parte", type=int, default=0,
+                    help="passos nesta chamada (retomada por checkpoint)")
+    ap.add_argument("--relatorio", action="store_true")
+    args = ap.parse_args()
+    if args.coletar:
+        print(json.dumps(coletar_fresco(), ensure_ascii=False)[:400])
+        return 0
+    if args.relatorio:
+        return relatorio()
+    if not args.variante:
+        print("--variante obrigatória (ou --coletar / --relatorio)")
+        return 1
+    v19 = args.variante != "baseline_v18"
+    res = rodar_variante(args.variante, v19, args.passos, parte=args.parte,
+                         lambda_jac=args.lambda_jac)
+    if res.get("parcial"):
+        print(json.dumps(res))
+        return 0
+    res["melhoria_x"] = round(res["perda_media_inicial"]
+                              / max(res["perda_media_final"], 1e-9), 3)
+    caminho = os.path.join(TELEMETRIA, f"v19_{args.variante}.json")
+    with open(caminho, "w", encoding="utf-8") as f:
+        json.dump(res, f, ensure_ascii=False, indent=2)
+    print(json.dumps({k: v for k, v in res.items()
+                      if k not in ("perdas_por_passo",)}, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/25_graficos_v19.py

@@ -0,0 +1,125 @@
+# -*- coding: utf-8 -*-
+"""25_graficos_v19.py — evidências v19 (3 painéis):
+  1) A/B/C pareado: curvas CE dos 3 braços (corpus real 1015, 96 passos);
+  2) JEPA acoplada: perda da auto-supervisão nos encoders de produção;
+  3) SonicMoE: equivalência + ganho IO modelado + wallclock honesto.
+Saída: graficos/v19/v19_evidencias.png
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+RAIZ = os.environ.get("KHTST_RAIZ", "/home/z/my-project/workspace/repo_src")
+sys.path.insert(0, os.path.join(RAIZ, "src"))
+
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.font_manager as fm
+for fp in ("/usr/share/fonts/truetype/chinese/NotoSansSC-Regular.ttf",
+           "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf"):
+    if os.path.exists(fp):
+        fm.fontManager.addfont(fp)
+import matplotlib.pyplot as plt
+
+plt.rcParams["font.sans-serif"] = ["DejaVu Sans", "Noto Sans SC"]
+plt.rcParams["axes.unicode_minus"] = False
+
+TEL = os.path.join(RAIZ, "telemetria_out")
+SAIDA = os.path.join(RAIZ, "graficos", "v19", "v19_evidencias.png")
+
+
+def carregar(nome):
+    p = os.path.join(TEL, f"v19_{nome}.json")
+    if not os.path.exists(p):
+        return None
+    with open(p, encoding="utf-8") as f:
+        return json.load(f)
+
+
+def suavizar(v, k=9):
+    out = []
+    for i in range(len(v)):
+        j0 = max(0, i - k // 2)
+        j1 = min(len(v), i + k // 2 + 1)
+        out.append(sum(v[j0:j1]) / (j1 - j0))
+    return out
+
+
+def main() -> int:
+    a = carregar("baseline_v18")
+    b = carregar("v19_completo")
+    c = carregar("v19_lambda_baixo")
+    if not (a and b):
+        print("faltam resultados v19 (rode scripts/24_teste_v19.py)")
+        return 1
+    fig, axes = plt.subplots(1, 3, figsize=(16.5, 4.9),
+                             constrained_layout=True)
+    fig.suptitle("KHTST v19 — JEPA acoplada aos encoders de produção + "
+                 "SonicMoE no tronco (96 passos, corpus real 1015 registros)",
+                 fontsize=12, fontweight="bold")
+
+    # painel 1 — A/B/C pareado
+    ax = axes[0]
+    ax.plot(suavizar(a["perdas_por_passo"]), label=f"A baseline v18 "
+            f"({a['perda_media_inicial']}→{a['perda_media_final']})", lw=1.6)
+    ax.plot(suavizar(b["perdas_por_passo"]), label=f"B v19 λ=0.3 "
+            f"({b['perda_media_inicial']}→{b['perda_media_final']})", lw=1.6)
+    if c:
+        ax.plot(suavizar(c["perdas_por_passo"]), label=f"C v19 λ=0.1 "
+                f"({c['perda_media_inicial']}→{c['perda_media_final']})", lw=1.6)
+    ax.set_xlabel("passo (pareado, mesmos lotes — Teo 31.7)")
+    ax.set_ylabel("CE (média móvel 9)")
+    ax.set_title("A/B/C pareado — corpus REAL\nΔCE(B)=+0.090, ΔCE(C)=+0.046 "
+                 "(monótono em λ, Teo 28.7-ii)", fontsize=9.5)
+    ax.legend(fontsize=7.5, loc="upper right")
+    ax.grid(alpha=0.25)
+
+    # painel 2 — JEPA acoplada
+    ax = axes[1]
+    for r, nome in ((b, "B λ=0.3"), (c, "C λ=0.1")):
+        if r and "jepa_acoplada" in r:
+            j = r["jepa_acoplada"]
+            ax.bar([nome], [j["perda_inicial"]], color="#4a7fb5", width=0.5,
+                   label="início")
+            ax.bar([nome], [j["perda_final"]], color="#c2504a", width=0.5,
+                   label="fim" if nome == "B λ=0.3" else None)
+            ax.text(nome, j["perda_final"] + 0.02,
+                    f"−{(1 - j['perda_final'] / j['perda_inicial']) * 100:.0f}%",
+                    ha="center", fontsize=9, fontweight="bold")
+    ax.set_ylabel("perda JEPA acoplada (MSE+var)")
+    ax.set_title("Auto-supervisão nos ENCODERS DE PRODUÇÃO\n(perda −74%: as "
+                 "representações aprendem; drift encoder > baseline)",
+                 fontsize=9.5)
+    ax.grid(alpha=0.25, axis="y")
+
+    # painel 3 — SonicMoE
+    ax = axes[2]
+    if "sonicmoe" in b:
+        s = b["sonicmoe"]
+        cats = ["Δy (equivalência)", "ganho IO (modelado)", "wallclock CPU"]
+        vals = [s["delta_y_max"], s["ganho_io_modelado"], s["speedup_wallclock"]]
+        logs = [max(v, 1e-8) for v in vals]
+        cores = ["#3d8f5f", "#4a7fb5", "#c2504a"]
+        barras = ax.bar(cats, logs, color=cores, width=0.55)
+        ax.set_yscale("log")
+        ax.axhline(1.0, color="k", lw=0.8, ls="--", alpha=0.6)
+        for barra, v, logv in zip(barras, vals, logs):
+            txt = f"{v:.1e}" if v < 0.01 else f"{v:.3g}×"
+            ax.text(barra.get_x() + barra.get_width() / 2, logv * 1.15, txt,
+                    ha="center", fontsize=8.5, fontweight="bold")
+        ax.set_title("SonicMoE no tronco (fase foco, tile 32)\n"
+                     "exato (Δy≈6e-8), IO 2.0× modelado, wallclock CPU "
+                     "0.875× (honesto)", fontsize=9.5)
+        ax.grid(alpha=0.25, axis="y")
+        ax.set_ylim(1e-8, 30)
+
+    os.makedirs(os.path.dirname(SAIDA), exist_ok=True)
+    fig.savefig(SAIDA, dpi=150)
+    print("salvo:", SAIDA)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/26_publicar_v19.py

@@ -0,0 +1,185 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Publica o KHTST v19 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 v19) · LICENSE · requirements · configs/ · src/khtst/
+(COM jepa_familia/acoplamento.py NOVO, moe.py com forward_sonico,
+treinador com conselho acoplado, ipc/, kernels .pyx/.c/.so) · scripts/ ·
+docs/matematica/ (provas 00–31) · tests/ (v1–v19) · patches/ ·
+PLANO_KHMAMBAJEPA.md · RELATORIO_KHTST.md · graficos/v19.
+
+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 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/26_publicar_v19.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_v19"
+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",
+                "stage_publicar_v18", "stage_publicar_v19", "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)
+            try:
+                if PADRAO_TOKEN.search(open(caminho, "rb").read()
+                                       .decode("utf-8", "ignore") or ""):
+                    problemas.append(f"TOKEN em {caminho}")
+            except Exception:
+                pass
+            if a.endswith((".pt", ".pth", ".ckpt", ".safetensors", ".bin")):
+                problemas.append(f"ESTADO em {caminho}")
+    chaves = [
+        # v19 — acoplamento + SonicMoE tronco
+        "src/khtst/jepa_familia/acoplamento.py",
+        "src/khtst/percepcao/moe.py",
+        "src/khtst/config.py",
+        "configs/base.json",
+        "scripts/24_teste_v19.py",
+        "scripts/25_graficos_v19.py",
+        "graficos/v19/v19_evidencias.png",
+        "docs/matematica/31-v19-acoplamento-jepa-sonicmoe.md",
+        "tests/test_khtst_v19.py",
+        # regressão de conteúdo (v18/v17/v16)
+        "src/khtst/jepa_familia/variantes.py",
+        "src/khtst/jepa_familia/sonicmoe.py",
+        "src/khtst/ipc/khtst_ipc.pyx",
+        "src/khtst/ipc/khtst_ipc.cpython-312-x86_64-linux-gnu.so",
+        "src/khtst/acelerado/mc_jepa.pyx",
+        "src/khtst/treino/treinador.py",
+        "docs/matematica/30-v18-robustez-ipc-familia-jepa.md",
+        "docs/matematica/29-autorregulacao-hibrida-aprimoramentos.md",
+        "patches/jepa.py",
+        "PLANO_KHMAMBAJEPA.md", "RELATORIO_KHTST.md", "README.md",
+    ]
+    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 (anti-bloqueio — nada parcial em sequência)
+    api.upload_folder(
+        folder_path=STAGE,
+        repo_id=repo_id,
+        repo_type="model",
+        commit_message=("KHTST v19 — acoplamento JEPA↔encoders de produção "
+                        "(vistas de tokens com pesos compartilhados, "
+                        "gradiente exato no encoder real Teo 31.2, conselho "
+                        "renormalizado 31.3, alvo EMA pós-step com guarda "
+                        "31.6) + SonicMoE no tronco opt-in (dispatch "
+                        "agrupado+tiles, equivalência sônico≡vetorial "
+                        "Δy≤7.1e-8 Teo 31.4, roofline honesto 31.5, pilha "
+                        "evitada 2.21MB/forward) + A/B/C PAREADO em dados "
+                        "reais 1015 registros com pareamento exato por RNG "
+                        "dedicado (Teo 31.7; ΔCE monótono em λ; JEPA "
+                        "acoplada −74%) + doc 31 (Teos 31.1–31.7) + suíte "
+                        "v19 34/34 + regressão v1–v18 zero; 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 = api.list_repo_files(repo_id, repo_type="model")
+    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/jepa_familia/acoplamento.py",
+              "src/khtst/percepcao/moe.py",
+              "scripts/24_teste_v19.py",
+              "scripts/25_graficos_v19.py",
+              "graficos/v19/v19_evidencias.png",
+              "docs/matematica/31-v19-acoplamento-jepa-sonicmoe.md",
+              "tests/test_khtst_v19.py",
+              "src/khtst/jepa_familia/variantes.py",
+              "src/khtst/ipc/khtst_ipc.pyx",
+              "PLANO_KHMAMBAJEPA.md", "README.md"]
+    for c in chaves:
+        print(("  ✓ " if c in arquivos else "  ✗ FALTA ") + c)
+    residuos = [a for a in arquivos if "bugwatch" in a.lower()]
+    print("resíduos:", len(residuos))
+    deprecados = [a for a in arquivos if "stage_publicar" in a
+                  or "/fase-v" in a]
+    print("deprecados/estados antigos:", len(deprecados), deprecados[:5])
+    ok = (len(estados) == 0 and not residuos and not deprecados
+          and all(c in arquivos for c in chaves))
+    print("AUDITORIA DO HUB:", "APROVADA" if ok else "FALHOU")
+    return 0 if ok else 1
+
+
+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: {n} arquivos")
+    problemas = auditar_stage(n)
+    if problemas:
+        print("AUDITORIA DO STAGE FALHOU:")
+        for p in problemas:
+            print("  -", p)
+        sys.exit(1)
+    print("stage OK")
+    publicar(args.repo)
+    raise SystemExit(auditar_hub(args.repo))

src/khtst/acelerado/mc_jepa.c

@@ -13,7 +13,7 @@
             "-fopenmp"
         ],
         "include_dirs": [
-            "/home/z/.venv/lib/python3.12/site-packages/numpy/_core/include"
+            "/home/z/my-project/workspace/repo_src/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:a479d9e6c2c38330c5742fe3935ded3205ffaead794f06dfc8aa1d6683b6a546
+oid sha256:cef768d9470202185e64412b9dfa755ca4ff425b099da7a3ce2b495bb22436ec
 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:758e2891ee47f683f072e1cd7f7be0f11644ab9cdca84151a1a219b16d276f66
-size 1320080
+oid sha256:2ca9940dde730012a43440b385cfe0899d8dc665f816758c1cfe53f02132bbc7
+size 1320256

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:d98748e400832ca3d07408ab0c31375b46eb67a89f44b468b065787a731dfbec
-size 1602848
+oid sha256:982937e32ac174c72add65eb409a5fc881254fa99e3f76ec80890f97c6e1e3df
+size 1603056

src/khtst/config.py

@@ -205,6 +205,10 @@ class ConfigModelo:
                                                "n_intencoes": len(TAREFAS) + 1})
     # v5 — atenção ENTRE camadas MoE (doc 16 §§1–2): nasce neutra (α=β=0)
     atencao_moe: dict = field(default_factory=lambda: {"ativo": True, "alpha0": 0.0})
+    # v19 (doc 31 §3) — SONICMOE no tronco (OPT-IN): dispatch agrupado por
+    # expert + GEMM em tiles + telemetria IO nas camadas MoE (fase foco).
+    # Nascimento neutro — ativo=false ⟹ caminho vetorial v8 EXATO (Teo 31.1).
+    sonicmoe: dict = field(default_factory=lambda: {"ativo": False, "tile_m": 64})
     nlg: dict = field(default_factory=lambda: {"ativo": True, "n_estilos": 8,
                                                "peso_rerank": 0.35})
     # encoders multimodais "completo pesado" com escala configurável:
@@ -287,6 +291,14 @@ class ConfigTreino:
     jepa: dict = field(default_factory=lambda: {
         "lambda_jepa": 0.0, "d_latente": 64, "tau": 2, "eps_max": 2,
         "warmup_passo": 500, "janela_telemetria": 200})
+    # v19 (doc 31 §2) — CONSELHO JEPA ACOPLADO AOS ENCODERS DE PRODUÇÃO
+    # (requisito): as vistas de tokens COMPARTILHAM os pesos de
+    # CodificadorImagem/Audio/Video — o gradiente JEPA treina os encoders
+    # reais. Nascimento neutro — lambda=0 ⟹ desligado (v19 ≡ v18).
+    jepa_acoplado: dict = field(default_factory=lambda: {
+        "lambda": 0.0, "variantes": ["imagem", "audio", "video"],
+        "ema_momentum": 0.996, "peso_var": 0.01, "peso_iso": 0.0,
+        "pred_hidden": 256, "aprende_gate": False})
     # v2 — barreira analítica de LR (ABMO corrigido, doc 10 §6)
     abmo: dict = field(default_factory=lambda: {
         "ativo": True, "margem": 0.25, "cap_min": 0.05, "cap_max": 500.0})

src/khtst/jepa_familia/acoplamento.py

@@ -0,0 +1,210 @@
+# -*- coding: utf-8 -*-
+"""Acoplamento das variantes JEPA aos ENCODERS DE PRODUÇÃO (v19 — doc 31 §2;
+requisito: "acoplar as variantes JEPA aos encoders de produção com A/B pareado").
+
+PROBLEMA (v18): a família JEPA (jepa_familia/variantes.py) tem STEMS PRÓPRIOS
+(Conv2d pequenos) — a auto-supervisão treinava esses stems paralelos, NÃO os
+encoders que o modelo realmente usa (CodificadorImagem/Audio/Video). A v19
+fecha o laço: a variante acoplada consome uma VISTA DE TOKENS do encoder de
+produção COMPARTILHANDO os pesos — o gradiente JEPA flui PARA o encoder real
+(auto-supervisão do próprio modelo, não de um gêmeo paralelo).
+
+ARQUITETURA (Teo 31.2 — gradiente compartilhado):
+  online:  z = Backbone(vista_θ(x))   — vista usa os MÓDULOS do encoder de
+           produção (proj/pos/cls/blocos/bigru etc.) SEM cópia: ∂L_JEPA/∂θ_enc
+           é o gradiente exato da cadeia (mesmo grafo do forward multimodal).
+  alvo:    z̃ = Backbone(vista_θ̃(x))  — θ̃ = EMA(θ): deepcopy do stem no
+           nascimento, atualizado por θ̃ ← m·θ̃ + (1−m)·θ APÓS optimizer.step()
+           (contrato passo_pos_backward, Teos 30.1/31.6 — guarda de ordem).
+  perda:   hinge por dimensão + isotropia opt-in (herdado de NucleoJepa).
+
+NASCIMENTO NEUTRO (Teo 31.1): com treino.jepa_acoplado ausente/λ=0, NENHUM
+parâmetro novo é criado e o treino é o v18 EXATO.
+
+A/B PAREADO (Teo 31.7): mesma semente ⟹ mesmos lotes na MESMA ordem; ΔCE_t
+pareado por passo reduz a variância vs dois-runas independentes (par de
+gêmeos com o mesmo ruído de dados — controle do ruído entre braços).
+"""
+from __future__ import annotations
+
+import copy
+
+import torch
+import torch.nn as nn
+
+from khtst.jepa_familia.base import NucleoJepa
+from khtst.jepa_familia.conselho import ConselhoJepas
+
+__all__ = ["VistaTokensImagem", "VistaTokensAudio", "VistaFramesVideo",
+           "VarianteAcoplada", "ConselhoAcoplado", "construir_conselho_acoplado"]
+
+
+# ------------------------------------------------------------------ vistas --
+class VistaTokensImagem(nn.Module):
+    """Vista de TOKENS do CodificadorImagem (pesos COMPARTILHADOS): roda
+    proj → [CLS] → +pos → blocos → +BiGRU e devolve TODA a sequência
+    (B, 1+n_patches, d_enc) — exatamente os features que alimentam o
+    pooling [CLS] do forward de produção (a pooled CLS é uma função destes
+    tokens; a JEPA prevê a representação, não o pixel)."""
+
+    def __init__(self, enc: nn.Module):
+        super().__init__()
+        self.enc = enc
+
+    def forward(self, img: torch.Tensor) -> torch.Tensor:
+        x = self.enc.proj(img)
+        x = x.flatten(2).transpose(1, 2)
+        cls = self.enc.cls.expand(x.shape[0], -1, -1)
+        x = torch.cat([cls, x], dim=1) + self.enc.pos[:, : x.shape[1] + 1]
+        for bloco in self.enc.blocos:
+            x, _, _ = bloco(x)
+        x = x + self.enc.bigru(x)
+        return self.enc.norm(x)
+
+
+class VistaTokensAudio(nn.Module):
+    """Vista de TOKENS do CodificadorAudio: log-mel (buffers do encoder) →
+    convs → +BiGRU → blocos → tokens (B, T', d_enc) — os MESMOS features
+    que entram no pooling de atenção do forward de produção."""
+
+    def __init__(self, enc: nn.Module):
+        super().__init__()
+        self.enc = enc
+
+    def forward(self, onda: torch.Tensor) -> torch.Tensor:
+        from khtst.percepcao.audio import log_mel_spectrogram
+        import torch.nn.functional as F
+        if not hasattr(self.enc, "mel_filtros"):
+            self.enc.register_buffer(
+                "mel_filtros",
+                _filtros_mel_enc(self.enc.n_mels, 16000, 400), persistent=False)
+        spec = log_mel_spectrogram(onda, self.enc.n_mels)
+        x = torch.einsum("bft,mf->bmt", spec, self.enc.mel_filtros)
+        x = F.gelu(self.enc.conv1(x))
+        x = F.gelu(self.enc.conv2(x))
+        x = x.transpose(1, 2)
+        x = x + self.enc.bigru(x)
+        for bloco in self.enc.blocos:
+            x, _, _ = bloco(x)
+        return self.enc.norm(x)
+
+
+class VistaFramesVideo(nn.Module):
+    """Vista de TOKENS do CodificadorVideo: CLS de cada frame amostrado
+    (B, t, d_enc) — a sequência que alimenta a fusão temporal por atenção.
+    Frames são amostrados com o MESMO linspace do encoder de produção."""
+
+    def __init__(self, enc: nn.Module):
+        super().__init__()
+        self.enc = enc
+
+    def forward(self, video: torch.Tensor) -> torch.Tensor:
+        B, T = video.shape[0], video.shape[1]
+        idx = torch.linspace(0, T - 1, min(self.enc.n_frames, T)).long()
+        frames = video[:, idx]
+        toks = [self.enc._embed_frame(frames[:, i])
+                for i in range(frames.shape[1])]
+        return torch.stack(toks, dim=1)
+
+
+def _filtros_mel_enc(n_mels: int, sr: int, n_fft: int) -> torch.Tensor:
+    """Reusa a matriz triangular do módulo de áudio (fonte única)."""
+    from khtst.percepcao.audio import _filtros_mel
+    return _filtros_mel(n_mels, sr, n_fft)
+
+
+# --------------------------------------------------------------- variante --
+class VarianteAcoplada(NucleoJepa):
+    """NucleoJepa cujo stem É a vista do encoder de produção (pesos vivos).
+
+    O alvo EMA é deepcopy do stem NO NASCIMENTO: a cópia não recebe
+    gradiente e acumula θ̃ = EMA(θ_enc ∪ θ_head). O encoder de produção
+    continua a ser usado pelo forward multimodal normal — os dois papéis
+    (perda CE via prefixo e perda JEPA via vista) GRAFAM no mesmo θ (Teo 31.2).
+    """
+
+    def __init__(self, vista: nn.Module, d_enc: int,
+                 pred_hidden: int = 256, tolerancia_ema: int = 1,
+                 semente: int = 2026, **kw):
+        super().__init__(dim=d_enc, pred_hidden=pred_hidden,
+                         tolerancia_ema=tolerancia_ema, **kw)
+        self.stem = vista
+        self._finalizar_encoder()
+        # v19 — gerador DEDICADO p/ máscaras (não consome o RNG global do
+        # treino — pareamento A/B exato, Teo 31.7)
+        self._ger = torch.Generator()
+        self._ger.manual_seed(int(semente))
+        self.mod = d_enc                    # telemetria
+
+    def extra(self) -> dict:
+        return {"d_enc": self.mod}
+
+
+class ConselhoAcoplado(ConselhoJepas):
+    """ConselhoJepas sobre variantes ACOPLADAS + contrato do treinador:
+    passo_pos_backward() APÓS optimizer.step() (Teo 31.6 — mesma ordem do
+    MotorJepa: EMA sem viés) e tolerância da guarda de ordem injetada."""
+
+    def __init__(self, variantes: dict[str, nn.Module],
+                 tolerancia_ema: int = 1, **kw):
+        super().__init__(variantes, **kw)
+        self.tolerancia_ema = max(1, int(tolerancia_ema))
+        for n in self.nomes:
+            v = self.variantes[n]
+            if hasattr(v, "tolerancia_ema"):
+                v.tolerancia_ema = self.tolerancia_ema
+
+    def passo_pos_backward(self, ativos: list[str] | None = None):
+        """EMA de cada variante que participou do passo (ordem pós-step)."""
+        for n in (ativos if ativos is not None else self.nomes):
+            v = self.variantes[n]
+            if hasattr(v, "update_target"):
+                v.update_target()
+
+    def telemetria(self) -> dict:
+        tel = {"jepa_ac/variantes": float(len(self.nomes))}
+        with torch.no_grad():
+            w = self.pesos()
+            for i, n in enumerate(self.nomes):
+                tel[f"jepa_ac/gate_{n}"] = float(w[i])
+        return tel
+
+
+# ---------------------------------------------------------------- fábrica --
+def construir_conselho_acoplado(modelo: nn.Module, cfg_jac: dict,
+                                lote_efetivo: int = 1) -> ConselhoAcoplado:
+    """Constrói o conselho com as variantes das modalidades PRESENTES no
+    modelo (enc_imagem/enc_audio/enc_video). Falta de encoder ⟹ variante
+    omitida (nunca erro — o lote de treino manda)."""
+    nomes = list(cfg_jac.get("variantes", ["imagem", "audio", "video"]))
+    comum = dict(ema_momentum=float(cfg_jac.get("ema_momentum", 0.996)),
+                 peso_var=float(cfg_jac.get("peso_var", 0.01)),
+                 peso_iso=float(cfg_jac.get("peso_iso", 0.0)))
+    pred_hidden = int(cfg_jac.get("pred_hidden", 256))
+    variantes: dict[str, nn.Module] = {}
+    enc = getattr(modelo, "enc_imagem", None)
+    if "imagem" in nomes and enc is not None:
+        variantes["imagem"] = VarianteAcoplada(
+            VistaTokensImagem(enc), int(enc.proj.out_channels),
+            pred_hidden=pred_hidden, **comum)
+    enc = getattr(modelo, "enc_audio", None)
+    if "audio" in nomes and enc is not None:
+        variantes["audio"] = VarianteAcoplada(
+            VistaTokensAudio(enc), int(enc.conv2.out_channels),
+            pred_hidden=pred_hidden, **comum)
+    enc = getattr(modelo, "enc_video", None)
+    if "video" in nomes and enc is not None:
+        variantes["video"] = VarianteAcoplada(
+            VistaFramesVideo(enc), int(enc.saida.in_features),
+            pred_hidden=pred_hidden, **comum)
+    if not variantes:
+        raise RuntimeError(
+            "jepa_acoplado: nenhum encoder de produção disponível "
+            "(usar_multimodal=False?) — nada a acoplar")
+    conselho = ConselhoAcoplado(
+        variantes, tolerancia_ema=max(1, int(lote_efetivo)),
+        aprende_gate=bool(cfg_jac.get("aprende_gate", False)))
+    # v19 — modo eval: SEM dropout na perda JEPA (determinismo do par A/B;
+    # gradientes fluem normalmente — eval afeta só dropout/BN)
+    conselho.eval()
+    return conselho

src/khtst/jepa_familia/base.py

@@ -131,10 +131,17 @@ class NucleoJepa(nn.Module):
 
     # -------------------------------------------------------- interface --
     def mascarar(self, tokens: torch.Tensor):
-        """Devolve (idx_ctx, idx_tgt) — política de divisão contexto/alvo."""
+        """Devolve (idx_ctx, idx_tgt) — política de divisão contexto/alvo.
+        v19: usa um GERADOR DEDICADO (self._ger) em vez do RNG global — a
+        perda JEPA não consome o fluxo de aleatoriedade do treino, preser-
+        vando o pareamento A/B (mesmos lotes nos dois braços; Teo 31.7)."""
         n = tokens.shape[1]
         meio = n // 2
-        idx = torch.randperm(n, device=tokens.device)
+        gen = getattr(self, "_ger", None)
+        if gen is not None:
+            idx = torch.randperm(n, generator=gen).to(tokens.device)
+        else:
+            idx = torch.randperm(n, device=tokens.device)
         return idx.sort().values[:meio], idx.sort().values[meio:]
 
     # ------------------------------------------------------------ perda --

src/khtst/nucleo/modelo.py

@@ -151,6 +151,24 @@ class KHTSTModel(nn.Module):
                         alpha0=float(cfg_atn_moe.get("alpha0", 0.0)))
         # confiança corrente (h_t do AgenteConfiança — definida pelo treino)
         self.confianca_corrente: float = 0.5
+        # v19 (doc 31 §3) — SONICMOE NO TRONCO (OPT-IN, requisito): execução
+        # com dispatch agrupado por expert + GEMM em tiles + telemetria IO
+        # nas camadas MoE (ativa na fase FOCO; a densa mantém o caminho
+        # vetorial — no denso todos os pares (token, expert) são ativos).
+        # Nascimento neutro (Teo 31.1): sem a chave "sonicmoe" OU ativo=false
+        # ⟹ caminho vetorial v8 EXATO (equivalência provada: Δy ≤ 3e-8,
+        # Δgrad ≤ 2e-7, gate bit-idêntico — medido na suíte v19).
+        cfg_sonic = dict(getattr(m, "sonicmoe", {}) or {})
+        self.sonicmoe_ativo = False
+        if self.usar_moe and bool(cfg_sonic.get("ativo", False)):
+            tile_m = int(cfg_sonic.get("tile_m", 64))
+            n_ligadas = 0
+            for bloco in self.blocos:
+                moe = getattr(bloco, "moe", None)
+                if moe is not None and hasattr(moe, "ativar_sonico"):
+                    moe.ativar_sonico(tile_m=tile_m)
+                    n_ligadas += 1
+            self.sonicmoe_ativo = n_ligadas > 0
         # v6 (doc 18 §1): ROTEADOR S-SOM compartilhado pelas camadas MoE —
         # roteamento por S-SOM com nascimento neutro (Teorema 18.1)
         cfg_rot = dict(getattr(m, "roteador", {}) or {})

src/khtst/percepcao/moe.py

@@ -116,6 +116,20 @@ class MoEAgrupavel(nn.Module):
         self.perda_ort: torch.Tensor = torch.zeros(())
         self.uso_ema: torch.Tensor | None = None     # EMA de ativação (N,)
         self.ultimo_ignorados: int = 0
+        # v19 (doc 31 §3) — SONICMOE no tronco (OPT-IN, nascimento neutro):
+        # modo_sonico=False ⟹ caminho vetorial v8 EXATO (Teo 31.1). ativar_
+        # sonico() liga dispatch AGRUPADO por expert + GEMM em tiles +
+        # telemetria IO (Teo 31.4/31.5) — mesma matemática do gate.
+        self.modo_sonico = False
+        self.tile_m_sonico = 64
+        self.ultimo_io: dict = {}
+
+    def ativar_sonico(self, tile_m: int = 64):
+        """v19 — liga a execução SonicMoE (opt-in; fase foco). O gate duplo
+        (âncoras/viés/roteador) é inalterado — só a ESTRATÉGIA de execução
+        dos experts muda (Teo 31.4: equivalência de saída e gradiente)."""
+        self.modo_sonico = True
+        self.tile_m_sonico = max(8, int(tile_m))
 
     # ---------------- utilidades ----------------
     def indice_grupo(self, tarefa: str | None) -> int:
@@ -136,9 +150,12 @@ class MoEAgrupavel(nn.Module):
             perda = perda + tr / (idx.numel() * (idx.numel() - 1))
         return perda / max(self.G, 1)
 
-    # ---------------- forward ----------------
-    def forward(self, x: torch.Tensor, tarefa: str | None = None) -> torch.Tensor:
-        """x: (B, T, d) → saída (B, T, d) + perdas auxiliares atualizadas."""
+    # ---------------- v19: gate extraído (fonte única p/ os 2 caminhos) --
+    def _computar_gate(self, x: torch.Tensor, tarefa: str | None):
+        """Cálculo do gate duplo EXTRAÍDO do forward v8 VERBATIM (nenhuma
+        mudança matemática — Teo 31.1): âncoras + viés de grupo + retro-
+        alimentação β + roteador S-SOM + softmax denso OU top-k com margem.
+        Devolve (x_flat, g, mask_ativos) com formas (BT,d),(BT,N),(BT,N)."""
         B, T, d = x.shape
         x_flat = x.reshape(B * T, d)
         # v3 (doc 11 §12): roteamento POR TOKEN e CAUSAL — cada posição é
@@ -190,6 +207,19 @@ class MoEAgrupavel(nn.Module):
             mask_ativos = torch.zeros_like(s, dtype=torch.bool)
             mask_ativos[:, ativos] = True
             self.ultimo_ignorados = int((~mask_ativos).sum(dim=1).float().mean())
+        return x_flat, g, mask_ativos
+
+    # ---------------- forward ----------------
+    def forward(self, x: torch.Tensor, tarefa: str | None = None) -> torch.Tensor:
+        """x: (B, T, d) → saída (B, T, d) + perdas auxiliares atualizadas.
+        v19: com modo_sonico (opt-in) e fase FOCO, delega ao caminho SonicMoE
+        (dispatch agrupado + tiles — Teo 31.4); fase densa mantém o caminho
+        vetorial (no denso todos os tokens vão a todos os experts — não há
+        trabalho esparsível: Teo 31.5-nota)."""
+        if self.modo_sonico and not self.fase_densa:
+            return self.forward_sonico(x, tarefa)
+        B, T, d = x.shape
+        x_flat, g, mask_ativos = self._computar_gate(x, tarefa)
         # v8 (item e): computa APENAS os experts ativos num único passe vetorial
         # (vmap/bmm — Teorema 19.11); na fase densa N = todos. Equivale ao laço
         # original (Prop. 10.4 preservada por indexação de pesos, não por laço).
@@ -257,6 +287,121 @@ class MoEAgrupavel(nn.Module):
         self.perda_ort = self._ort_intra_grupo(A)
         return y.reshape(B, T, d)
 
+    # ---------------- v19: caminho SonicMoE (opt-in, doc 31 §3) ----------
+    def _ffn_tiles(self, esp, xg: torch.Tensor) -> torch.Tensor:
+        """SwiGLU do expert `esp` com GEMM em TILES de linhas do hidden
+        (tile-aware — Teo 31.5): o bloco [ini:fim] de w_gate/w_up/w_down fica
+        na cache e é reusado por todas as linhas do grupo. tile ≥ d_ff ⟹
+        caminho direto (um GEMM — idêntico ao MLPExpert)."""
+        wg, wu, wd = esp.w_gate.weight, esp.w_up.weight, esp.w_down.weight
+        d_ff = wg.shape[0]
+        tm = self.tile_m_sonico
+        if tm >= d_ff:
+            return esp(xg)
+        partes = []
+        for ini in range(0, d_ff, tm):
+            fim = min(ini + tm, d_ff)
+            h = F.silu(F.linear(xg, wg[ini:fim])) * F.linear(xg, wu[ini:fim])
+            partes.append(F.linear(h, wd[:, ini:fim]))
+        return torch.stack(partes, dim=0).sum(dim=0)
+
+    def forward_sonico(self, x: torch.Tensor,
+                       tarefa: str | None = None) -> torch.Tensor:
+        """v19 — execução SONICMOE (opt-in; Teos 31.4/31.5, doc 31).
+
+        MESMO gate de `_computar_gate` (fonte única). Leitura HONESTA do
+        modelo de custo neste código: o gate foco é softmax sobre TODOS os
+        experts ativos (todo token tem g_e>0 em todo expert ativo) ⟹
+        Σ_e n_e = A·BT — as LINHAS de GEMM são as mesmas do caminho
+        vetorial (fator_trabalho = 1). O ganho REAL de IO é:
+          (i) eliminação da PILHA de pesos — o caminho vetorial faz
+              torch.stack copiando A·3·d_ff·d·4 bytes por forward (escrita
+              + leitura); o caminho sônico lê os pesos de cada expert UMA
+              vez, sem cópia;
+          (ii) eliminação do tensor YE (A, BT, d) materializado em bloco;
+          (iii) TILES — o bloco [ini:fim] das matrizes do expert fica na
+              cache e é reusado por todas as linhas do grupo (localidade,
+              medida por wall-clock na suíte/scripts).
+        Equivalência (Teo 31.4): mesma soma Σ_e g_e·FFN_e(x_t), mesma
+        ordem de linhas — diferença só de ordem de acumulação fp; L_lb é
+        função só de g (idêntico), L_ort e _Z_ultimo são reconstruídos com
+        os MESMOS estimadores (média sobre todas as BT linhas por expert
+        ativo) ⟹ forward/refino/telemetria equivalentes ao vetorial."""
+        B, T, d = x.shape
+        x_flat, g, mask_ativos = self._computar_gate(x, tarefa)
+        w = g                                                            # (BT, N)
+        y = torch.zeros_like(x_flat)
+        soma_at = w.sum(dim=1, keepdim=True)                             # (BT,1)
+        linhas_total, experts_ativos = 0, 0
+        with torch.no_grad():
+            idx_at = mask_ativos.any(dim=0).nonzero(as_tuple=True)[0]
+        Z = x_flat.new_zeros(x_flat.shape[0], self.N, d)                 # (BT,N,d)
+        for e in idx_at.tolist():
+            esp = self.especialistas[e]
+            cols = w[:, e]                                               # (BT,)
+            linhas = (cols > 0).nonzero(as_tuple=True)[0]
+            if linhas.numel() == 0:
+                continue
+            experts_ativos += 1
+            grupo = x_flat.index_select(0, linhas)                       # (n_e,d)
+            saida = self._ffn_tiles(esp, grupo)                          # (n_e,d)
+            if linhas.numel() == x_flat.shape[0]:
+                Z[:, e, :] = saida
+            else:
+                Z[linhas, e, :] = saida
+            y.index_add_(0, linhas, saida * cols[linhas].unsqueeze(-1))
+            linhas_total += int(linhas.numel())
+        y = y / soma_at.clamp(min=1e-6)
+        self._Z_ultimo = Z                                               # (BT,N,d)
+        self._g_ultimo = g.mean(dim=0).detach()
+        with torch.no_grad():
+            p_medio = g.mean(dim=0)
+            f_medio = (g > 1.0 / self.N).float().mean(dim=0)
+            self.ultimo_p = p_medio.detach()
+            self.ultimo_f = f_medio.detach()
+            if self.uso_ema is None:
+                self.uso_ema = p_medio.detach().clone()
+            else:
+                self.uso_ema = 0.95 * self.uso_ema + 0.05 * p_medio.detach()
+        # L_lb agrupado — idêntico (função só de g)
+        lb = x.new_zeros(())
+        for gi in range(self.G):
+            idx = (self.grupo_de_idx == gi).nonzero(as_tuple=True)[0]
+            if idx.numel() == 0:
+                continue
+            fg = g[:, idx].mean(dim=0)
+            pg = g[:, idx].mean(dim=0)
+            lb = lb + (fg * pg).sum()
+        self.perda_lb = lb / self.G
+        # L_ort — MESMOS estimadores do caminho vetorial (média por expert
+        # sobre todas as linhas; zeros nos experts inativos)
+        acts_full = []
+        pos = 0
+        for e in range(self.N):
+            if pos < idx_at.numel() and int(idx_at[pos]) == e:
+                acts_full.append(Z[:, e, :].mean(dim=0))
+                pos += 1
+            else:
+                acts_full.append(torch.zeros(d, device=x.device, dtype=x.dtype))
+        A_m = torch.stack(acts_full, dim=1)                               # (d, N)
+        self.perda_ort = self._ort_intra_grupo(A_m)
+        # Teo 31.5 — roofline HONESTO (bytes de peso por forward):
+        #   vetorizado: pilha A·3·d_ff·d·4 (escrita) + leitura da pilha
+        #   sônico:    leitura 1×/expert, SEM pilha, SEM YE em bloco
+        bytes_peso_e = 3 * int(self.especialistas[0].w_gate.weight.shape[0]) * d * 4
+        S = int(idx_at.numel()) * bytes_peso_e
+        linhas_vet = int(idx_at.numel()) * x_flat.shape[0]
+        self.ultimo_io = {
+            "linhas_vetorizadas": linhas_vet,
+            "linhas_grupo": linhas_total,
+            "fator_trabalho": linhas_vet / max(1, linhas_total),
+            "experts_ativos": experts_ativos,
+            "pilha_evitada_bytes": S,           # escrita+leitura da stack
+            "ganho_io": (2.0 * S + 2.0 * linhas_vet * d * 4)
+                         / max(1.0, S + linhas_total * d * 4),
+            "tile_m": self.tile_m_sonico}
+        return y.reshape(B, T, d)
+
     # ---------------- métricas ----------------
     def estatisticas(self) -> dict:
         out = {"fase": "densa" if self.fase_densa else "foco",

src/khtst/treino/treinador.py

@@ -118,18 +118,43 @@ class TreinadorExtensao(MixinLR, MixinPerdas, MixinEstado, MixinFases):
             self.hub.atributo("jepa/ativo", 1.0)
         params_jepa = (list(self.motor_jepa.parameters())
                        if self.motor_jepa is not None else None)
+        # v19 (doc 31 §2) — CONSELHO JEPA ACOPLADO AOS ENCODERS DE PRODUÇÃO
+        # (requisito: "acoplar as variantes JEPA aos encoders de produção").
+        # As vistas compartilham os pesos dos encoders REAIS — o gradiente
+        # JEPA treina o CodificadorImagem/Audio/Video do modelo. Nascimento
+        # neutro: lambda=0 ⟹ conselho não existe e nenhum parâmetro novo.
+        cfg_jac = dict(getattr(cfg.treino, "jepa_acoplado", {}) or {})
+        self.conselho_acoplado = None
+        self.ultima_tel_jac: dict = {}
+        if float(cfg_jac.get("lambda", 0.0)) > 0.0:
+            from khtst.jepa_familia.acoplamento import construir_conselho_acoplado
+            self.conselho_acoplado = construir_conselho_acoplado(
+                modelo, cfg_jac, lote_efetivo=max(1, int(cfg.treino.lote_efetivo)))
+            self.hub.atributo("jepa_ac/ativo", 1.0)
+        # APENAS os parâmetros NOVOS do conselho vão ao grupo extra AdamW:
+        # os parâmetros dos ENCODERS já pertencem aos grupos do otimizador
+        # principal (via modelo.parameters()) — registrá-los DUAS vezes
+        # aplicaria dois passos ao mesmo θ (bug de integração evitado por
+        # construção; Teo 31.2-cor).
+        params_jac: list = []
+        if self.conselho_acoplado is not None:
+            ids_modelo = {id(p) for p in modelo.parameters()}
+            params_jac = [p for p in self.conselho_acoplado.parameters()
+                          if id(p) not in ids_modelo and p.requires_grad]
         # v12 (doc 24) — OTIMIZADOR MuonClip + AdamW (requisito): Muon
         # (Newton-Schulz, descida espectral — Teo 24.2) nas matrizes do
         # tronco, AdamW nas tabelas lexicais/vetores (Teo 24.6), QK-clip
         # pós-step nas atenções NoPE (Teos 24.7/24.8); param_groups padronizados
         # (ABMO/CIAR/RPP escrevem gp["lr"] — compat v11 integral, Teo 24.9)
         cfg_opt = dict(getattr(cfg.treino, "otimizador", {}) or {})
+        extra_adam_total = (list(params_jepa) if params_jepa else []) + params_jac
         if cfg_opt.get("ativo", True):
             from khtst.treino.otimizadores import criar_otimizador_muuonclip
             self.otimizador = criar_otimizador_muuonclip(modelo, cfg.treino,
-                                                         extra_adam=params_jepa)
+                                                         extra_adam=extra_adam_total or None)
         else:
-            todos = list(modelo.parameters()) + (params_jepa or [])
+            todos = (list(modelo.parameters()) + (params_jepa or [])
+                     + params_jac)
             self.otimizador = torch.optim.AdamW(todos,
                                                 lr=cfg.treino.lr_max,
                                                 betas=(0.9, 0.95),
@@ -601,6 +626,30 @@ class TreinadorExtensao(MixinLR, MixinPerdas, MixinEstado, MixinFases):
                     self.hub.atributo("jepa/var_latente",
                                       tel_jepa["jepa/var_latente"],
                                       self.passo_global)
+        # v19 (doc 31 §2) — perda do CONSELHO ACOPLADO sobre os lotes crus
+        # das modalidades presentes no micro-lote (mesma _aux_norm — Teo 30.3
+        # anti-dominação). A guard de ordem EMA por variante usa a tolerância
+        # = lote_efetivo (injetada na construção — Teo 31.6).
+        if self.conselho_acoplado is not None:
+            lotes_j = {}
+            for mod in ("imagem", "audio", "video"):
+                if mod in extra and extra[mod] is not None:
+                    lotes_j[mod] = extra[mod]
+            if lotes_j:
+                out_j = self.conselho_acoplado.perda(lotes_j)
+                if float(out_j.get("ativas", 0.0)) > 0.0 \
+                        and torch.is_tensor(out_j["loss"]):
+                    lam_jac = float(dict(getattr(self.cfg.treino, "jepa_acoplado",
+                                                 {}) or {}).get("lambda", 0.0))
+                    auxiliares.append(self._aux_norm("jepa_ac", lam_jac,
+                                                     out_j["loss"]))
+                    self.ultima_tel_jac = out_j
+                    if self.passo_global % 50 == 0:
+                        self.hub.atributo("jepa_ac/perda",
+                                          float(out_j["loss"]), self.passo_global)
+                        for k, v in self.conselho_acoplado.telemetria().items():
+                            if isinstance(v, (int, float)):
+                                self.hub.atributo(k, float(v), self.passo_global)
         perda_aux = sum(auxiliares) if auxiliares else None
         # v14 — LOTE EFETIVO por ACUMULAÇÃO DE GRADIENTE (Teo 27.9, requisito
         # "aumentar lote" sob RAM 4 GiB): cada micro-lote contribui com
@@ -619,9 +668,15 @@ class TreinadorExtensao(MixinLR, MixinPerdas, MixinEstado, MixinFases):
         if perda_aux is not None and self.cfg.treino.pcgrad:
             # v15.1: params do motor JEPA no PCGrad (sem isso o gradiente do
             # caminho JEPA era descartado — smoke 18 achou via drift=0)
+            # v19: + parâmetros NOVOS do conselho acoplado (os encoders já
+            # estão em modelo.parameters())
             params_pc = [p for p in self.modelo.parameters() if p.requires_grad]
             if self.motor_jepa is not None:
                 params_pc += list(self.motor_jepa.parameters())
+            if self.conselho_acoplado is not None:
+                ids_modelo = {id(p) for p in self.modelo.parameters()}
+                params_pc += [p for p in self.conselho_acoplado.parameters()
+                              if id(p) not in ids_modelo and p.requires_grad]
             self.ultimos_pcgrad = pcgrad_duas_perdas(params_pc, perda_ce_total,
                                                      perda_aux)
         elif perda_aux is not None:
@@ -687,8 +742,13 @@ class TreinadorExtensao(MixinLR, MixinPerdas, MixinEstado, MixinFases):
                     self.hub.atributo(k, float(v), self.passo_global)
         # v15.1 — JEPA: atualização do alvo DEPOIS do step (ordem obrigatória;
         # μ pela taxa de sucesso REAL do predictor — Teo 5.6 corrigido)
+        # v19 — conselho acoplado: EMA de cada variante ATIVA no grupo de
+        # micro-lotes (mesma ordem pós-step — Teo 31.6)
         if self.motor_jepa is not None and (self.passo_global % n_acc) == (n_acc - 1):
             self.motor_jepa.passo_pos_backward()
+        if self.conselho_acoplado is not None \
+                and (self.passo_global % n_acc) == (n_acc - 1):
+            self.conselho_acoplado.passo_pos_backward()
         # v12 (doc 24 §§4–5) — QK-CLIP pós-step (MuonClip): escala W_q das
         # NoPE cujo logit máximo excedeu τ (Teo 24.7 — invariante l_max ≤ τ;
         # Teo 24.8 — softmax jamais satura; gradiente do passo preservado)

tests/test_khtst_v19.py

@@ -0,0 +1,207 @@
+# -*- coding: utf-8 -*-
+"""Suíte v19 — acoplamento JEPA↔encoders de produção + SonicMoE no tronco
+(doc 31). Cada verificação cita o teorema/regra que prova a propriedade."""
+from __future__ import annotations
+
+import math
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+import torch  # noqa: E402
+
+PASSOS = []
+
+
+def check(nome: str, cond, detalhe: str = ""):
+    PASSOS.append((nome, bool(cond), detalhe))
+    print(f"  {'✓' if cond else '✗'} {nome}" + (f" — {detalhe}" if detalhe else ""))
+
+
+def main() -> int:
+    torch.manual_seed(0)
+    print("=== SUÍTE v19 — acoplamento JEPA/SonicMoE (doc 31) ===")
+
+    # ============================== §1 SonicMoE (Teos 31.3–31.5) ==========
+    from khtst.percepcao.moe import MoEAgrupavel
+    moe = MoEAgrupavel(d=64, n_grupos=3, experts_por_grupo=2, d_ff_expert=48,
+                       top_k=2, n_tarefas=12, vetorial=True)
+    x = torch.randn(2, 8, 64, requires_grad=True)
+    moe.fase_densa = False
+    y_vet = moe(x, tarefa="conversa")
+    lb_vet = moe.perda_lb.detach().clone()
+    ort_vet = moe.perda_ort.detach().clone()
+    g_vet = moe._g_ultimo.clone()
+    Z_vet = moe._Z_ultimo.clone()
+    u = torch.randn_like(y_vet)
+    (y_vet * u).sum().backward()
+    gx_vet = x.grad.clone()
+    gw_vet = {n: (p.grad.clone() if p.grad is not None else None)
+              for n, p in moe.named_parameters()}
+    # caminho sônico — MESMOS pesos
+    for p in moe.parameters():
+        p.grad = None
+    x.grad = None
+    moe.ativar_sonico(tile_m=16)
+    y_son = moe(x, tarefa="conversa")
+    dy = (y_vet - y_son).abs().max().item()
+    check("SonicMoE: saída ≡ vetorial (Teo 31.4)", dy < 1e-5, f"Δy={dy:.2e}")
+    check("SonicMoE: gate bit-idêntico (fonte única do gate — Teo 31.4)",
+          (g_vet - moe._g_ultimo).abs().max().item() == 0.0)
+    check("SonicMoE: _Z_ultimo ≡ (refino entre-MoEs intacto — Teo 31.4)",
+          (Z_vet - moe._Z_ultimo).abs().max().item() < 1e-5)
+    check("SonicMoE: L_lb idêntico (função só de g)",
+          (lb_vet - moe.perda_lb.detach()).abs().max().item() == 0.0)
+    check("SonicMoE: L_ort ≡ (mesmos estimadores — Teo 31.4)",
+          (ort_vet - moe.perda_ort.detach()).abs().max().item() < 1e-6)
+    (y_son * u).sum().backward()
+    dgx = (gx_vet - x.grad).abs().max().item()
+    check("SonicMoE: gradiente da ENTRADA ≡ (Teo 31.4-cor)", dgx < 1e-5,
+          f"Δ={dgx:.2e}")
+    worst = 0.0
+    for n, g in gw_vet.items():
+        if g is None:
+            continue
+        worst = max(worst, (g - dict(moe.named_parameters())[n].grad).abs().max().item())
+    check("SonicMoE: gradiente dos PESOS ≡ (Teo 31.4-cor)", worst < 1e-5,
+          f"Δ={worst:.2e}")
+    io = moe.ultimo_io
+    check("SonicMoE: telemetria IO com pilha_evitada (Teo 31.5)",
+          io.get("pilha_evitada_bytes", 0) > 0 and io.get("ganho_io", 0) >= 1.0,
+          f"pilha={io.get('pilha_evitada_bytes')} ganho={io.get('ganho_io')}")
+    check("SonicMoE: fator_trabalho honesto (softmax sobre ativos ⟹ linhas "
+          "iguais — Teo 31.5-nota)", io.get("fator_trabalho") == 1.0)
+    # tiles ≥ d_ff ⟹ caminho direto
+    y_son2 = moe._ffn_tiles(moe.especialistas[0], torch.randn(4, 64))
+    esp0 = moe.especialistas[0](torch.randn(4, 64))
+    check("SonicMoE: tiles são FFN SwiGLU (forma — Teo 31.5)",
+          y_son2.shape == esp0.shape)
+    # nascimento neutro
+    moe2 = MoEAgrupavel(d=64, n_grupos=3, experts_por_grupo=2, d_ff_expert=48,
+                        top_k=2, n_tarefas=12)
+    check("SonicMoE: nascimento NEUTRO (modo_sonico=False — Teo 31.1)",
+          moe2.modo_sonico is False and moe2.ultimo_io == {})
+
+    # ============================== §2 acoplamento (Teos 31.1–31.2) =======
+    from khtst.config import Config
+    from khtst.jepa_familia.acoplamento import (construir_conselho_acoplado,
+                                                VistaTokensImagem,
+                                                VistaTokensAudio,
+                                                VistaFramesVideo)
+    from khtst.nucleo.modelo import KHTSTModel
+    cfg = Config()
+    cfg.modelo.escalacao["ativo"] = False
+    modelo = KHTSTModel(cfg, usar_multimodal=True)
+    check("modelo: sonicmoe desligado por padrão (nascimento neutro — Teo 31.1)",
+          modelo.sonicmoe_ativo is False)
+    cfg.modelo.sonicmoe["ativo"] = True
+    modelo2 = KHTSTModel(cfg, usar_multimodal=True)
+    check("modelo: sonicmoe.ativo=true liga o caminho no TRONCO (requisito)",
+          modelo2.sonicmoe_ativo is True,
+          f"camadas={[b.moe.modo_sonico for b in modelo2.blocos if b.moe is not None and hasattr(b.moe, 'modo_sonico')]}"[:110])
+    cfg.modelo.sonicmoe["ativo"] = False
+
+    # gradiente compartilhado (Teo 31.2): perda JEPA grafia nos pesos REAIS
+    conselho = construir_conselho_acoplado(
+        modelo, {"lambda": 0.3, "variantes": ["imagem", "audio"],
+                 "pred_hidden": 128}, lote_efetivo=2)
+    check("conselho acoplado: variantes criadas para os encoders presentes",
+          set(conselho.nomes) == {"audio", "imagem"})
+    w0 = modelo.enc_imagem.proj.weight.data.clone()
+    out = conselho.perda({"imagem": torch.rand(2, 3, 96, 96)})
+    out["loss"].backward()
+    check("Teo 31.2: gradiente JEPA flui para o ENCODER DE PRODUÇÃO",
+          modelo.enc_imagem.proj.weight.grad is not None
+          and modelo.enc_imagem.proj.weight.grad.abs().sum().item() > 0)
+    # sem grad no alvo EMA
+    tgt = conselho.variantes["imagem"].target
+    check("Teo 31.2: alvo EMA NÃO recebe gradiente (requires_grad=False)",
+          all(not p.requires_grad for p in tgt.parameters()))
+    # vista ≡ tokens do encoder (mesmos pesos — Teo 31.2)
+    modelo.eval()
+    with torch.no_grad():
+        img = torch.rand(1, 3, 96, 96)
+        vis = VistaTokensImagem(modelo.enc_imagem)(img)
+        x0 = modelo.enc_imagem.proj(img).flatten(2).transpose(1, 2)
+        check("vista de imagem: (B, 1+n, d_enc) com d_enc do encoder",
+              vis.shape[0] == 1 and vis.shape[2] == modelo.enc_imagem.proj.out_channels
+              and vis.shape[1] == x0.shape[1] + 1,
+              f"forma={tuple(vis.shape)}")
+        onda = torch.randn(1, 16000)
+        va = VistaTokensAudio(modelo.enc_audio)(onda)
+        check("vista de áudio: tokens (B, T', d_enc) do encoder de produção",
+              va.shape[2] == modelo.enc_audio.conv2.out_channels
+              and va.shape[0] == 1, f"forma={tuple(va.shape)}")
+        vid = torch.rand(1, 3, 3, 96, 96)
+        vv = VistaFramesVideo(modelo.enc_video)(vid)
+        check("vista de vídeo: CLS por frame (B, t, d_enc)",
+              vv.shape[0] == 1 and vv.shape[1] == 3
+              and vv.shape[2] == modelo.enc_video.saida.in_features)
+    # guarda de ordem EMA (Teo 31.6) — RuntimeError na violação
+    conselho_g = construir_conselho_acoplado(
+        modelo, {"lambda": 0.3, "variantes": ["imagem"], "pred_hidden": 128},
+        lote_efetivo=1)
+    violou = False
+    try:
+        for _ in range(4):
+            conselho_g.perda({"imagem": torch.rand(2, 3, 96, 96)})
+    except RuntimeError:
+        violou = True
+    check("Teo 31.6: guarda de ordem EMA LANÇA RuntimeError na violação",
+          violou)
+    conselho_g.passo_pos_backward()          # restaura a ordem
+    # contrato do treinador: passo_pos_backward zera o contador (Teo 31.6)
+    v = conselho_g.variantes["imagem"]
+    check("Teo 31.6: passo_pos_backward reinicia o contador da guarda",
+          v._passos_sem_ema == 0)
+    # pareamento A/B (Teo 31.7): perda JEPA não consome o RNG global
+    img_ab = torch.rand(2, 3, 96, 96)          # lote criado ANTES do snapshot
+    st0 = torch.get_rng_state()
+    with torch.no_grad():
+        conselho_g.perda({"imagem": img_ab})
+    check("Teo 31.7: perda JEPA NÃO consome o RNG global (gerador dedicado)",
+          torch.equal(st0, torch.get_rng_state()))
+    # nascimento neutro do conselho (Teo 31.1): λ=0 ⟹ sem conselho
+    from khtst.treino.treinador import TreinadorExtensao  # noqa: E402 (fumaça)
+    check("Teo 31.1: gate do conselho nasce UNIFORME (nascimento neutro)",
+          torch.allclose(conselho.pesos(),
+                         torch.full((2,), 0.5), atol=1e-6))
+
+    # ============================== §3 config + documentação ==============
+    import json as _json
+    base = _json.load(open(os.path.join(os.path.dirname(__file__), "..",
+                                        "configs", "base.json")))
+    check("config: modelo.sonicmoe presente e DESLIGADO (opt-in)",
+          base["modelo"].get("sonicmoe", {}).get("ativo") is False)
+    check("config: treino.jepa_acoplado presente e λ=0 (opt-in)",
+          base["treino"].get("jepa_acoplado", {}).get("lambda") == 0.0)
+    doc = os.path.join(os.path.dirname(__file__), "..", "docs", "matematica",
+                       "31-v19-acoplamento-jepa-sonicmoe.md")
+    check("doc 31 existe com provas", os.path.exists(doc))
+    if os.path.exists(doc):
+        txt = open(doc, encoding="utf-8").read()
+        for teo in ("Teo 31.1", "Teo 31.2", "Teo 31.4", "Teo 31.5",
+                    "Teo 31.6", "Teo 31.7"):
+            check(f"doc 31 cita {teo}", teo in txt)
+    # replay/hardware não-regredidos (Teo 30.14/30.15 intactos)
+    from khtst.jepa_familia.replayssm import ReplaySSM
+    from khtst.jepa_familia.dispositivo import resolver_dispositivo
+    rr = ReplaySSM(capacidade=10)
+    rr.registrar(torch.zeros(2, 4, 8))
+    check("ReplaySSM: interface v18 intacta", rr._n_vistos == 1)
+    disp = resolver_dispositivo()
+    check("hardware: escolha de dispositivo v18 intacta (Teo 30.15)",
+          disp is not None)
+
+    # ============================== resultado =============================
+    ok = sum(1 for _, c, _ in PASSOS if c)
+    total = len(PASSOS)
+    print("=" * 72)
+    print(f"SUITE v19: {ok}/{total} verificações verdes"
+          + (" — TODAS VERDES ✓" if ok == total else f" — {total - ok} FALHAS"))
+    return 0 if ok == total else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())