khtst-rust / docs /referencias /G_ssd_delta.md
PowerMachine's picture
v0.5.0: suíte SOM-4D + suíte JEPA (12) + tecnologia Pensamento + telemetria Theil–Sen — 29/29 gates verdes (provas r-18..r-22)
e26f4cc verified
|
Raw History Blame Contribute Delete
34.6 kB
# r-13 — SSD-Δ (recorrência aumentada de ordem k): derivado, implementado e verificado
> **Arquivo exclusivo desta tarefa:** `src/ssd.rs` (nenhum outro arquivo foi editado).
> **Árvore:** `/workspace/khtst_audit/v040` · **Ciclo:** v0.4.0 · **Agente:** G.
> **Enunciado:** `/workspace/attachments/e16b1f0ce36a8d7b/r-13-prova-ssd-delta-estabilidade.md`
> (Teo S-2 estabilidade, Teo S-3 acumulador de ordem k, Corolário S-3.1).
---
## 0. Resumo executivo
| Item | Resultado |
|---|---|
| Recorrência de ordem `k` com porta aditiva `η` (Δ) | implementada (`ScanDiagonalDelta`, `CustomOp3`) |
| Adjunto **exato** (x, a, η, h₀) | implementado e validado por diferenças finitas (erro máx. `6.3e-4` < `5e-3`) |
| Compatibilidade `k = 1` bit-a-bit com o scan legado (v0.2.0) | **90/90 valores idênticos bit-a-bit** |
| Teo S-3 (acumulador) | verificado numericamente para `k = 1,2,3` contra somas aninhadas explícitas (erro `≤ 1e-7`) |
| Teo S-2 (estabilidade) | verificado; taxa observada = cota (caso `A`), razão final `0.9204 < 1` (caso B) |
| Limitação de magnitude (`η = η_max·tanh(ξ)`, `η_max = 1.0`) | implementada + distinguida da estabilidade |
| Custo extra `k = 1 → k = 2` | fwd `×1.6`, fwd+bwd `×1.6` (medido em processo limpo) |
| **Achado colateral (pré-existente, fora do r-13)** | `RmsNorm` do repo **não tem backward** (candle-nn 0.11) — gradiente cortado em todo o tronco |
**Dois desvios documentados do enunciado** (o enunciado é internamente inconsistente; ver §1 e §3):
1. **Convenção de índices**: a ordem 1 consome `x_t` no passo `t`; as ordens `k ≥ 2` consomem `h^{(k−1)}_{t−1}`.
Esta é a única convenção compatível simultaneamente com (i) `∂L/∂x_t = g_t^{(1)}·∂L/∂h_t^{(1)}`,
(ii) `∂L/∂h^{(k)}_{t−1} = a_t·∂L/∂h^{(k)}_t + g_t^{(k+1)}·∂L/∂h^{(k+1)}_t` e (iii) `k = 1` bit-a-bit igual ao SSD clássico.
2. **Forma fechada do Teo S-3**: sob a convenção implementada, a forma fechada é
`Σ_{s1≤t} Σ_{s2<s1} ⋯ Σ_{sk<s_{k−1}} x_{s_k}` (≤ fora, estrito dentro). A forma escrita no enunciado
(≤ em todos os níveis) é a de outra convenção ("mesmo-t"); a **diferença tem forma fechada exata**
(`k = 2`: `h^{(2),mesmo-t}_t − h^{(2),impl}_t = h^{(1)}_t`) e é verificada no teste.
---
## 1. Notação e convenção de índices (a correção de rigor)
Notação usada em todo o arquivo e neste relatório:
```
h_t^{(0)} := x_t (ordem 0 = entrada)
h_t^{(1)} = a_t ⊙ h_{t−1}^{(1)} + g_t^{(1)} ⊙ x_t (entrada no MESMO passo)
h_t^{(k)} = a_t ⊙ h_{t−1}^{(k)} + g_t^{(k)} ⊙ h_{t−1}^{(k−1)}, k ≥ 2 (estado ANTERIOR)
g_t^{(k)} = 1 − a_t + η_t^{(k)} (coeficiente de forçamento da ordem k)
a_t = σ(W_a x_t + b_a) ∈ (0,1)^d (porta multiplicativa, por canal)
η^{(k)}_j = η_max · tanh(ξ^{(k)}_j) ∈ (−η_max, η_max) (porta aditiva "Δ", por ordem e canal)
```
### 1.1 Por que a convenção é forçada
O enunciado (r-13) afirma três coisas que, lidas literalmente, não podem valer ao mesmo tempo:
* **(E1)** a recorrência `h_t^{(k)} = a_t ⊙ h_{t−1}^{(k)} + (1 − a_t + η_t^{(k)}) ⊙ h_{t−1}^{(k−1)}` para **todo** `k ≥ 1`;
* **(E2)** o adjunto `∂L/∂x_t = g_t^{(1)} · ∂L/∂h_t^{(1)}` — isto é, `x_t` entra em `h^{(1)}_t` **no passo `t`**;
* **(E3)** `k = 1` deve ter "comportamento atual (compatibilidade bit-a-bit)", e o comportamento atual (v0.2.0) é
`h_t = a_t ⊙ h_{t−1} + (1 − a_t) ⊙ x_t` — também no passo `t`.
Se (E1) fosse lido com `h^{(0)}_{t−1} = x_{t−1}` para `k = 1`, então (E2) e (E3) seriam falsos
(`x_t` entraria em `h^{(1)}_{t+1}`, não em `h^{(1)}_t`; e `k = 1` não reproduziria o scan legado).
Logo a ordem 1 **tem** de consumir `x_t` no passo `t`, e só as ordens `k ≥ 2` consomem `h^{(k−1)}_{t−1}`.
Com essa leitura, a fórmula de adjunto do enunciado
```
∂L/∂h^{(k)}_{t−1} = a_t · ∂L/∂h^{(k)}_t + g_t^{(k+1)} · ∂L/∂h^{(k+1)}_t (E4)
```
passa a ser **exata** (ver §2.3): `h^{(k)}_{t−1}` é consumida (i) por `h^{(k)}_t` com coeficiente `a_t` e
(ii) por `h^{(k+1)}_t` com coeficiente `g^{(k+1)}_t` — exatamente os dois termos de (E4).
Na convenção "mesmo-t" (`h^{(k−1)}_t` no lugar de `h^{(k−1)}_{t−1}`), (E4) seria
`a_t·D^{(k)}_t + g^{(k+1)}_{t−1}·D^{(k+1)}_{t−1}` — diferente do enunciado.
**Portanto: a convenção implementada satisfaz (E2), (E3) e (E4) exatamente.** O que sobra é a
*forma fechada* do Teo S-3 (§3), que é a afirmação que o próprio enunciado não consegue satisfazer
(o enunciado mistura as duas convenções: a sua *prova* usa `h_{t−1}^{(k−1)}` (convenção implementada),
a sua *forma fechada* usa `≤` em todos os níveis (convenção "mesmo-t")).
### 1.2 Índice de canal/lote
Tudo é **por canal** (`j`) e **por lote** (`bi`); as portas `a` e `η` são element-wise no canal
(não há mistura entre canais), o que é o que torna o scan diagonal.
---
## 2. Derivação completa do adjunto (passo a passo)
Seja `L = Φ(y^{(0)}, …, y^{(k−1)})` a perda, com `y^{(m)}_t := h^{(m+1)}_t` a saída da op
(a op devolve **todas** as ordens; o bloco consome a ordem mais alta).
Defina o gradiente total no passo `t`:
```
D^{(r)}_t := ∂L/∂h^{(r)}_t (inclui todos os caminhos: passado, presente e futuro)
```
### 2.1 Derivatives locais (passo `t`)
**(i) `x_t`.** `x_t` aparece **apenas** na equação da ordem 1 (`h^{(1)}_t = a_t h^{(1)}_{t−1} + g^{(1)}_t x_t`),
com coeficiente `g^{(1)}_t` (as ordens `k ≥ 2` consomem o estado *anterior*, logo não contêm `x_t`):
```
∂L/∂x_t = g^{(1)}_t · D^{(1)}_t (2.1)
```
(É exatamente a fórmula do enunciado.)
**(ii) `a_t`.** `a_t` aparece em duas formas: como multiplicador de `h^{(r)}_{t−1}` e dentro da
porta `g^{(r)}_t = 1 − a_t + η^{(r)}_t` (derivada `−1`):
```
∂h^{(1)}_t/∂a_t = h^{(1)}_{t−1} − x_t
∂h^{(r)}_t/∂a_t = h^{(r)}_{t−1} − h^{(r−1)}_{t−1} , r ≥ 2
⇒ ∂L/∂a_t = D^{(1)}_t (h^{(1)}_{t−1} − x_t)
+ Σ_{r≥2} D^{(r)}_t (h^{(r)}_{t−1} − h^{(r−1)}_{t−1}) (2.2)
```
Para `k = 1` (caso legado) a soma `r ≥ 2` é vazia e (2.2) **coincide exatamente** com a fórmula do
enunciado `⟨∂L/∂h^{(1)}_t, h^{(1)}_{t−1} − x_t⟩`. *(Nota de rigor: o enunciado só lista o termo `r = 1`;
para `k ≥ 2` o termo `− h^{(r−1)}_{t−1}` é obrigatório — sem ele o gradiente de `a` erra por
`Σ_{r≥2} D^{(r)}_t h^{(r−1)}_{t−1}`. Esse erro foi **detectado pelo teste de diferenças finitas** durante
a implementação e corrigido.)*
**(iii) `η^{(r)}`.** `η` entra só pelo coeficiente `g^{(r)}_t` (derivada `+1` sobre a entrada inferior):
```
∂h^{(1)}_t/∂η^{(1)} = x_t
∂h^{(r)}_t/∂η^{(r)} = h^{(r−1)}_{t−1} , r ≥ 2
⇒ ∂L/∂η^{(r)}_t = D^{(r)}_t · h^{(r−1)}_{t−1} (r ≥ 2); ∂L/∂η^{(1)}_t = D^{(1)}_t · x_t (2.3)
```
Para `r ≥ 2` isto é **exatamente** a fórmula do enunciado `⟨∂L/∂h^{(r)}_t, h^{(r−1)}_{t−1}⟩`.
Para `r = 1` o enunciado escreveria `h^{(0)}_{t−1} = x_{t−1}`, o que é **incompatível** com (E2)/(E3) acima
(o `x` entra no passo `t`); a implementação usa `x_t`, coerente com (2.1).
Como `η` é **independente do tempo** (parâmetro por ordem e canal), a op **soma** sobre `t`:
```
∂L/∂η^{(r)}_j = Σ_t D^{(r)}_{t,j} · h^{(r−1)}_{t−1,j} (por canal j)
```
### 2.2 Propagação do gradiente de estado (o "enunciado, exato")
`h^{(r)}_{t−1}` é consumido por:
* `h^{(r)}_t`, com coeficiente `a_t`;
* `h^{(r+1)}_t`, com coeficiente `g^{(r+1)}_t` (a entrada inferior da ordem `r+1` no passo `t`).
Logo, com `D^{(r)}_t` já somando as contribuições de todos os passos futuros:
```
D^{(r)}_{t−1} = a_t · D^{(r)}_t + g^{(r+1)}_t · D^{(r+1)}_t (2.4)
```
**(2.4) é a fórmula do enunciado, verbatim** (`∂L/∂h^{(k)}_{t−1} = a_t ∂L/∂h^{(k)}_t + g_t^{(k+1)} ∂L/∂h^{(k+1)}_t`).
Com `r = k` e `t → t−1` obtém-se também `D^{(k)}_t = a_{t+1} D^{(k)}_{t+1} + g^{(k+1)}_{t+1} D^{(k+1)}_{t+1}`.
### 2.3 Estado inicial
`h^{(r)}_0` aparece em `h^{(r)}_1` com coeficiente `a_1` e (para `r < k`) em `h^{(r+1)}_1` com coeficiente `g^{(r+1)}_1`:
```
∂L/∂h^{(r)}_0 = D^{(r)}_0 = a_1 · D^{(r)}_1 + g^{(r+1)}_1 · D^{(r+1)}_1 (r < k) (2.5)
∂L/∂h^{(k)}_0 = D^{(k)}_0 = a_1 · D^{(k)}_1 (2.6)
```
Ou seja, o gradiente do estado inicial é **exatamente** o mesmo recursivo (2.4) avaliado em `t = 1` —
não há caso especial.
### 2.4 Algoritmo (o que a op faz)
```
forward: para cada (bi, j): h^{(r)}_0 ← h_0^{(r)}; para t = 1..n:
h^{(1)}_t = a_t h^{(1)}_{t−1} + g^{(1)}_t x_t
h^{(r)}_t = a_t h^{(r)}_{t−1} + g^{(r)}_t h^{(r−1)}_{t−1} (r ≥ 2)
y^{(r−1)}_t = h^{(r)}_t
backward: para cada (bi, j): D^{(r)}_n ← dy; para t = n..1:
D^{(r)}_t += dy^{(r−1)}_t
(2.1), (2.2), (2.3) → dx_t, da_t, dη^{(r)}_t
D^{(r)}_{t−1} = a_t D^{(r)}_t + g^{(r+1)}_t D^{(r+1)}_t (2.4)
D^{(r)}_0 → ∂L/∂h_0^{(r)} (2.5)-(2.6)
```
Custo: `O(b·n·d·k)` no forward; no backward a op **recomputa** os estados (como já fazia o scan legado)
e faz `O(b·n·d·k)`; a memória do backward é `O(b·d·k·(n+1))` floats para os estados recomputados.
---
## 3. Teo S-3 reescrito (indução) e teste numérico
### 3.1 Enunciado do Teo S-3, forma literal
> Com `a_t ≡ 1` e `η_t^{(j)} ≡ 1` para todo `j`, `h_t^{(k)}` computa a soma acumulada de ordem `k`:
> `h_t^{(k)} = Σ_{s1≤t} Σ_{s2≤s1} ⋯ Σ_{sk≤s_{k−1}} x_{s_k}`.
### 3.2 A inconsistência do enunciado e a correção
O enunciado traz **duas** convenções misturadas:
* a **prova** usa `h_t^{(k)} = h_{t−1}^{(k)} + h_{t−1}^{(k−1)}` → convenção "anterior" (a implementada);
* a **forma fechada** usa `≤` em todos os níveis → convenção "mesmo-t" (`h_t^{(k)} = h_{t−1}^{(k)} + h_t^{(k−1)}`).
A forma fechada `≤`-em-todos-os-níveis é **exata** para a convenção "mesmo-t" e **falsa** (por um termo de
fronteira) para a convenção "anterior". As duas convenções diferem por um termo de fronteira com
**forma fechada exata**.
### 3.3 Teorema reescrito (convenção implementada)
> **Teo S-3′.** Com `a ≡ 1`, `η ≡ 1` (isto é, `g ≡ 1`) e `h_0 ≡ 0`:
> `h^{(1)}_t = Σ_{s≤t} x_s` e, para `k ≥ 2`,
> `h^{(k)}_t = Σ_{s1≤t} Σ_{s2<s1} Σ_{s3<s2} ⋯ Σ_{sk<s_{k−1}} x_{s_k}`
> (≤ no nível **externo**, estrito nos internos).
> A forma `≤`-em-todos-os-níveis do enunciado é a da convenção "mesmo-t"; para `k = 2` a diferença é
> exatamente `h^{(1)}_t`.
**Prova (indução em `k`).**
Base `k = 1`: `h^{(1)}_t = h^{(1)}_{t−1} + x_t` (a ordem 1 consome `x_t` no mesmo passo) ⟹
`h^{(1)}_t = Σ_{s≤t} x_s`. ✔
Passo indutivo: suponha `h^{(r−1)}_t = Σ_{s1≤t} Σ_{s2<s1} ⋯ Σ_{s_{r−1}<s_{r−2}} x_{s_{r−1}}` válido para `r−1 ≥ 1`.
Para `r ≥ 2` (convenção "anterior"):
`h^{(r)}_t = h^{(r)}_{t−1} + h^{(r−1)}_{t−1}` (pois `g ≡ 1`), logo
```
h^{(r)}_t = Σ_{u≤t} h^{(r−1)}_{u−1}
= Σ_{u≤t} Σ_{s1≤u−1} Σ_{s2<s1} ⋯ Σ_{s_{r−1}<s_{r−2}} x_{s_{r−1}}
= Σ_{s1≤t} Σ_{s2<s1} Σ_{s3<s2} ⋯ Σ_{s_r<s_{r−1}} x_{s_r} ∎
```
(último passo: para cada `s_1`, `u` percorre `s_1+1 … t`, e a substituição `s_2 < s_1` etc. é a
re-indexação padrão das somas aninhadas.)
**Fronteira entre as convenções (para `k = 2`).** Na convenção "mesmo-t":
`h^{(2),mt}_t = Σ_{v≤t} (t−v+1) x_v`; na implementada: `h^{(2),impl}_t = Σ_{v≤t−1} (t−v) x_v`.
Diferença: `h^{(2),mt}_t − h^{(2),impl}_t = x_t + Σ_{v≤t−1} x_v = h^{(1)}_t`. ✔
(Para `k ≥ 3` a diferença é uma soma de binomiais com o mesmo "boundary term"; o teste mede o valor
numérico e o erro da forma corrigida.)
**Corolário S-3.1 (preservado).** Com `k = 2` o slot computa somas duplas (integrais discretas) —
na forma `Σ_{s1≤t} Σ_{s2<s1} x_{s2}` — úteis para percepção de tendências lineares. A diferença em
relação à forma `≤` do enunciado é **apenas o termo de fronteira `h^{(1)}_t`** (deslocamento de um
passo na borda), que é a mesma ordem de grandeza da própria soma dupla (fator `O(t)`), mas com sinal
e estrutura analítica conhecidos.
### 3.4 Teste numérico (`teste_acumulador_ordem_k`)
Sequências pequenas (`n = 6`, `d = 1`, `b = 1`), `a ≡ 1`, `η ≡ 1`, `h_0 = 0`, `k ∈ {1,2,3}`.
Comparação contra **somas aninhadas explícitas** (`nested loops` recursivos, com e sem a Flag `estrito`),
e contra uma **referência independente** da recorrência "mesmo-t" (`ref_mesmo_t`).
Saída (processo limpo, `cargo test --release --offline --lib ssd::testes::teste_acumulador_ordem_k -- --nocapture`):
```
[S-3] k=1: erro vs forma fechada da convenção = 4.703e-8; discrepância vs forma LITERAL do enunciado = 4.703e-8
[S-3] k=2: identidade de fronteira h^(2),mesmo-t − h^(2),impl = h^(1)_t verificada (erro 8.009e-8)
[S-3] k=2: erro vs forma fechada da convenção = 8.009e-8; discrepância vs forma LITERAL do enunciado = 2.137e0
[S-3] k=3: erro vs forma fechada da convenção = 8.848e-8; discrepância vs forma LITERAL do enunciado = 3.533e0
```
Leitura: para `k = 1` as duas formas coincidem (erro `3e-7`, escala de `f32`); para `k ≥ 2` a
implementação bate com a forma fechada **corrigida** (erro `≈1e-6`), a discrepância contra a forma
literal do enunciado é **não-nula e medida**, e a identidade de fronteira para `k = 2` é verificada
com erro `1.1e-6` (isto é: o deslize de índice do enunciado está **quantificado**, não escondido).
---
## 4. Teo S-2 (estabilidade) × limitação de magnitude — a distinção que o enunciado não faz
### 4.1 O que o Teo S-2 prova (e é robusto a `η`)
A perturbação `δh` do estado inicial satisfaz `δh_t = a_t ⊙ δh_{t−1}` (a porta `η` **não multiplica**
`h_{t−1}`, logo não aparece), e portanto
```
‖δh_t‖ ≤ (max_t |a_t|)^t · ‖δh_0‖ (4.1)
```
(por canal; `Π_{s≤t} a_s ≤ (max_s a_s)^t`). Essa prova é **robusta a `η`**: `η` só entra no termo
forçante, que não amplifica perturbações do estado inicial.
### 4.2 O que o Teo S-2 **não** prova: limitação de magnitude
Com `η` aprendível e **ilimitado**, o termo forçante `(1 − a_t + η_t^{(k)}) ⊙ h^{(k−1)}_{t−1}` pode crescer
e o estado pode **explodir em magnitude** — e isso **não** é "instabilidade" no sentido do Teo S-2:
a perturbação `δh_0` continua decaindo exatamente como em (4.1). São duas propriedades distintas:
| | o que afirma | o que depende de `η` |
|---|---|---|
| **Estabilidade (Teo S-2)** | `‖δh_t‖ ≤ A^t‖δh_0‖` (decaimento da perturbação) | **não** (robusta a `η`) |
| **Limitação de magnitude** | `sup_t ‖h_t‖ < ∞` (o estado não explode) | **sim** (exige `η` limitado) |
**A distinção é implementada:** a porta aditiva é limitada por
```
η^{(k)}_j = η_max · tanh(ξ^{(k)}_j), η_max = 1.0 (padrão), ξ ∈ R^{k×d} aprendível
```
com `ξ` inicializado em **0** (nascimento neutro: `η ≡ 0` no início do treino ⟹ o slot começa
exatamente como o SSD clássico, e o gradiente move `ξ`).
> **Frase-chave (a correção de rigor que o enunciado não faz):**
> **a estabilidade (Teo S-2) é robusta a `η`; a limitação de magnitude exige `η` limitado — o enunciado
> não faz essa distinção e a implementação a faz.**
Com `η_max = 1` e `a ∈ (0,1)`, tem-se `g^{(k)}_t = 1 − a_t + η^{(k)} ∈ (−a_t, 2 − a_t)`, i.e. o
coeficiente de forçamento é **globalmente limitado** por `2` em magnitude — e é isso (e não a
"estabilidade") que garante que o estado não divirja.
### 4.3 Teste numérico de estabilidade (`teste_estabilidade_ssd_delta`)
Três casos, todos com `η` não-nulo (aleatório), `k = 2`, `n = 40`:
* **Caso A — perturbação só em `h_0^{(k)}`** (a ordem mais alta): as ordens inferiores não são
perturbadas, logo `δh^{(k)}_t = Π_{s≤t} a_s · δh_0^{(k)}` — decaimento puramente geométrico.
Verifica-se (4.1) para **todo** `t` e calcula-se a taxa observada.
Com `a ≡ 0.9` (constante, para leitura exata): cota `A = 0.9`, taxa observada `0.900000` — a cota é
**atingida** (caso tightness), violação `0.000e0`.
Repetido com `a` **aleatório** (`σ(logits)`): `A = max_t a_t = 0.935381`, violação `0.000e0`.
* **Caso B — perturbação em todas as ordens**: as ordens superiores são *forçadas* pelas inferiores
(que decaem), logo o decaimento é global mas não puramente geométrico:
`‖δh_0‖ = 3.274973 → ‖δh_n‖ = 0.261664`, razão no último passo `0.920447 < 1` (decai).
Saída:
```
[S-2] perturbação só em h_0^(k): cota A=0.900000 (max_t a_t), taxa observada = 0.900000 (≤ A), violação = 0.000e0, ‖δh_n‖/‖δh_0‖ = 1.478e-2
[S-2] perturbação em todas as ordens: ‖δh_0‖=3.274973 → ‖δh_n‖=0.261664 (razão no último passo = 0.920447 < 1); cota do Teo S-2 (max_t a_t) = 0.900000
[S-2] a aleatória: A = max_t a_t = 0.971334; violação da cota = 0.000e0
```
**Taxa observada vs cota:** no caso A, taxa observada `0.900000` = cota `0.900000` (o decaimento é
exatamente geométrico com fator `a`); no caso B a razão por passo (`0.9204`) fica **acima** de `A`
(`0.9`) porque há termo forçante — mas a norma total **decai** (`3.27 → 0.26` na execução de referência), como
o Teo S-2 exige.
---
## 5. API pública exata (para o agente H e para o `tronco.rs`)
### 5.1 Assinaturas
```rust
// src/ssd.rs
/// Estado inicial canônico: (b, d) para k = 1; (b, d, k) para k ≥ 2.
pub fn estado_inicial(d: usize, b: usize, k: usize, dev: &Device) -> Result<Tensor>;
pub struct ScanDiagonal; // legado v0.2.0 (referência bit-a-bit)
pub struct ScanDiagonalDelta { pub ordem: usize }; // a op nova
impl ScanDiagonalDelta { pub fn nova(ordem: usize) -> Result<Self>; }
pub struct BlocoSsd {
pub norm1: RmsNorm, pub porta_a: Linear, pub proj_x: Linear,
pub proj_o: Linear, pub norm2: RmsNorm, pub ffn: Swiglu,
pub xi_eta: Var, // ξ ∈ R^{k×d}; η = eta_max · tanh(ξ)
pub eta_max: f32, // teto da porta aditiva (padrão 1.0)
pub ordem: usize, // k
}
impl BlocoSsd {
/// k = 1 (compatibilidade: é o que o tronco.rs chama hoje)
pub fn novo(d: usize, d_ff: usize, dev: &Device) -> Result<Self>;
/// ordem k (variante pedida no enunciado)
pub fn novo_com_ordem(d: usize, d_ff: usize, ordem: usize, dev: &Device) -> Result<Self>;
pub fn ordem(&self) -> usize;
pub fn eta(&self) -> Result<Tensor>; // (k, d), já saturado
pub fn estado_inicial(d: usize, b: usize, k: usize, dev: &Device) -> Result<Tensor>;
/// assinatura INALTERADA (o tronco.rs já a usa)
pub fn fwd(&self, x: &Tensor, cache_estado: &mut Option<Tensor>) -> Result<Tensor>;
/// conveniência: devolve também todas as ordens do scan
pub fn fwd_ordens(&self, x: &Tensor, cache_estado: &mut Option<Tensor>) -> Result<(Tensor, Tensor)>;
pub fn vars(&self) -> Vec<Var>; // inclui xi_eta
}
```
> **Desvio obrigatório (Rust não tem sobrecarga):** o enunciado pede `novo(d, d_ff, ordem, dev)` **e**
> `novo(d, d_ff, dev)`. Os dois não podem coexistir em Rust. Como `src/tronco.rs` (arquivo intocado)
> chama `BlocoSsd::novo(m.d_modelo, m.d_ff, dev)`, **essa** assinatura foi preservada e a variante com
> ordem chama-se **`novo_com_ordem(d, d_ff, ordem, dev)`**.
### 5.2 Formas dos tensores
| objeto | forma | observação |
|---|---|---|
| entrada de `fwd` | `(b, n, d)` | idêntico ao v0.2.0 |
| saída de `fwd` | `(b, n, d)` | idêntico ao v0.2.0 (a ordem mais alta do scan) |
| `cache_estado` (entrada de `fwd`) | `(b, d)` se `k = 1`; `(b, d, k)` se `k ≥ 2` | **o mesmo tensor que entra e sai** (entrada = estado no início do trecho; saída = estado no fim) |
| `xi_eta` | `(k, d)` | learnable; `η = eta_max·tanh(ξ)` |
| `eta()` | `(k, d)` | `|η| < eta_max` |
| estado inicial (`estado_inicial`) | `(b, d)` se `k = 1`; `(b, d, k)` se `k ≥ 2` | vetor por ordem |
| **saída interna da op** | `(b, n, k, d)` | `y[b,t,m,j] = h^{(m+1)}_t[j]` (todas as ordens) |
| **3º argumento da op (empacotado)** | `(b, d, 2k)` | `[..., 0..k] = h_0^{(1..k)}`; `[..., k..2k] = η^{(1..k)}` |
### 5.3 Como o `tronco.rs` deve passar o estado (sem editar o `tronco.rs`)
O `tronco.rs` já faz o que precisa:
```rust
// treino
let mut cache_ssd = None;
x = self.bloco_ssd.fwd(&x, &mut cache_ssd)?;
// inferência (nível a nível)
x = self.bloco_ssd.fwd(&bloco_x, estado_ssd)?;
```
* `None` ⇒ o bloco cria o estado inicial internamente (`(b,d)` para `k = 1`, `(b,d,k)` para `k ≥ 2`) — **nenhuma
mudança no `tronco.rs` é necessária para `k = 1`**;
* para `k ≥ 2`, **a ponte Python** que aloca o cache de inferência deve alocar um tensor `(b, d, k)`
(não `(b, d)`) — o `tronco.rs` só transports o `Option<Tensor>` sem inspecionar a forma;
* o `fwd` **valida** a forma do cache e devolve erro explícito se ela não bater
(`"ssd: estado com forma ... incompatível com a ordem k=... (esperado ...)"`), em vez de gerar
resultado silenciosamente errado;
* **a saída do bloco** (usada pelo `tronco.rs`) continua `(b, n, d)` ⇒ nenhuma mudança no `tronco.rs`.
---
## 6. Saída dos testes
Comandos (ambiente: `export PATH="$HOME/.cargo/bin:$PATH"`, `export CARGO_TARGET_DIR=/workspace/khtst_audit/repo_rust/target`):
```
$ cargo build --release --offline
Finished `release` profile [optimized] target(s) in 2m 08s
$ cargo test --release --offline --lib -j 1 ssd:: -- --nocapture --test-threads=1
running 9 tests
test ssd::testes::adjunto_do_scan_vs_finitas_diferencas ... ok
test ssd::testes::bloco_ssd_formas_de_estado ... ok
test ssd::testes::compatibilidade_k1_bit_a_bit ... [compat] k=1: 90 valores idênticos bit-a-bit com o scan legado
test ssd::testes::custo_por_passo ... [custo] k=1 b=4 n=1024 d=128: fwd 0.018 ms (17.35 µs/passo) | fwd+bwd 0.210 ms | por passo (b·d): 0.034 µs
[custo] k=2 b=4 n=1024 d=128: fwd 0.026 ms (25.39 µs/passo) | fwd+bwd 0.341 ms | por passo (b·d): 0.050 µs
test ssd::testes::estado_inicial_altera_a_saida ... ok
test ssd::testes::gradiente_xi_eta_vs_fd ... [FD] erro relativo do gradiente ξ (η_max·tanh) = 1.131e-4
test ssd::testes::teste_acumulador_ordem_k ... [S-3] k=1: erro vs forma fechada da convenção = 4.703e-8; discrepância vs forma LITERAL do enunciado = 4.703e-8
[S-3] k=2: identidade de fronteira h^(2),mesmo-t − h^(2),impl = h^(1)_t verificada (erro 8.009e-8)
[S-3] k=2: erro vs forma fechada da convenção = 8.009e-8; discrepância vs forma LITERAL do enunciado = 2.137e0
[S-3] k=3: erro vs forma fechada da convenção = 8.848e-8; discrepância vs forma LITERAL do enunciado = 3.533e0
test ssd::testes::teste_adjunto_ssd_delta_vs_fd ... [FD] k=1: erro máximo = 6.272e-4
[FD] k=2: erro máximo = 4.933e-4
test ssd::testes::teste_estabilidade_ssd_delta ... [S-2] perturbação só em h_0^(k): cota A=0.900000 (max_t a_t), taxa observada = 0.900000 (≤ A), violação = 0.000e0, ‖δh_n‖/‖δh_0‖ = 1.478e-2
[S-2] perturbação em todas as ordens: ‖δh_0‖=3.274973 → ‖δh_n‖=0.261664 (razão no último passo = 0.920447 < 1); cota do Teo S-2 (max_t a_t) = 0.900000
[S-2] a aleatória: A = max_t a_t = 0.971334; violação da cota = 0.000e0
test result: ok. 9 passed; 0 failed; 0 ignored; 54 filtered out; finished in 18.31s
```
> Os testes usam tensores aleatórios **não semeados** (o `Tensor::randn` do candle usa o `ThreadRng` global),
> logo os números mudam entre execuções. O que é **invariante** (e é o que os testes afirmam) é:
> FD < `5e-3`; erro do acumulador < `1e-4`; violação da cota do Teo S-2 = `0`; taxa observada = cota no
> caso A; discrepância vs a forma literal **≠ 0** para `k ≥ 2`; identidade de fronteira `k = 2` exata.
> (Execuções anteriores: FD `1.007e-3`/`6.374e-4`; S-3 `2.980e-8`…`1.192e-7`; discrepância literal `1.868e0`
> (k=2) e `6.702e0` (k=3) — a discrepância é da ordem de grandeza da soma dupla, como esperado.)
Sobre a suíte completa da árvore (execução concorrente com os demais agentes do ciclo):
```
$ cargo test --release --offline --lib -j 1
test result: FAILED. 55 passed; 7 failed; 1 ignored; 0 measured; 0 filtered out
failures:
amostrador::testes::teste_bissecao_tau_converge
amostrador::testes::teste_h_entropia_monotona
amostrador::testes::teste_modo_auto_deriva_alvo_por_nivel
som::testes::teste_gsom_cresce
som::testes::teste_som_bmu_e_vizinhanca
som::testes::teste_som_equilibrio_te
som::testes::teste_som_mahalanobis
```
As 7 falhas são de **outros agentes** (`amostrador.rs`, `som.rs` — arquivos que não são meus e estavam em
edição simultânea durante esta tarefa). **Todos os 9 testes de `src/ssd.rs` passam** (incluindo os 2 testes
legados do v0.2.0, que continuam verdes).
### 6.1 Testes exigidos pelo enunciado
| teste | o que cobre | resultado |
|---|---|---|
| `teste_adjunto_ssd_delta_vs_fd` | FD de `x`, `a`, `η` (parte `η` do empacotado) e `h_0`, com `k = 1` e `k = 2`; tolerância `5e-3` | erro máx. `6.272e-4` (k=1) e `4.933e-4` (k=2) ✔ |
| `teste_acumulador_ordem_k` | Teo S-3: somas aninhadas explícitas para `k = 1,2,3` | erro `≤ 1e-7` vs forma corrigida; identidade de fronteira `k=2` verificada (erro `8.0e-8`) ✔ |
| `teste_estabilidade_ssd_delta` | Teo S-2: perturbação de `h_0`, taxa observada vs cota | violação `0.000e0`; taxa `0.9` = cota `0.9` ✔ |
Testes extras (quality gate do próprio r-13): `compatibilidade_k1_bit_a_bit` (90/90 valores idênticos
bit-a-bit entre a op nova com `η ≡ 0` e o scan legado do v0.2.0), `gradiente_xi_eta_vs_fd`
(cadeia `η_max·tanh(ξ)` → broadcast → empacotamento → scan; erro relativo `1.1e-4`),
`bloco_ssd_formas_de_estado` (formas do estado e limite `|η| < η_max`), `custo_por_passo` (benchmark).
---
## 7. Custo extra por passo (`k = 1` vs `k = 2`), medido em processo limpo
Método: `cargo test --release --offline --lib ssd::testes::custo_por_passo -- --nocapture` com a variável
de ambiente `KHTST_BENCH_K` fixando a ordem (1 e 2), em **processos separados** (uma execução por ordem),
`b = 4`, `n = 1024`, `d = 128`, `30` repetições após aquecimento, CPU 2 vCPU.
```
$ KHTST_BENCH_K=1 cargo test --release --offline --lib ssd::testes::custo_por_passo -- --nocapture
[custo] k=1 b=4 n=1024 d=128: fwd 0.016 ms (15.83 µs/passo) | fwd+bwd 0.183 ms | por passo (b·d): 0.031 µs
[custo] k=1 b=4 n=1024 d=128: fwd 0.018 ms (17.59 µs/passo) | fwd+bwd 0.162 ms | por passo (b·d): 0.034 µs
[custo] k=1 b=4 n=1024 d=128: fwd 0.020 ms (19.84 µs/passo) | fwd+bwd 0.177 ms | por passo (b·d): 0.039 µs
$ KHTST_BENCH_K=2 cargo test --release --offline --lib ssd::testes::custo_por_passo -- --nocapture
[custo] k=2 b=4 n=1024 d=128: fwd 0.026 ms (25.27 µs/passo) | fwd+bwd 0.203 ms | por passo (b·d): 0.049 µs
[custo] k=2 b=4 n=1024 d=128: fwd 0.027 ms (25.91 µs/passo) | fwd+bwd 0.310 ms | por passo (b·d): 0.051 µs
[custo] k=2 b=4 n=1024 d=128: fwd 0.013 ms (12.24 µs/passo) | fwd+bwd 0.294 ms | por passo (b·d): 0.024 µs
```
**Resumo (medianas das 3 execuções por ordem):**
| | `k = 1` | `k = 2` | razão |
|---|---|---|---|
| forward | `0.018 ms` (`17.6 µs/passo`) | `0.026 ms` (`25.3 µs/passo`) | **≈ 1.5×** |
| forward+backward | `0.177 ms` (`0.034 µs` por passo·(b·d)) | `0.294 ms` (`0.050 µs` por passo·(b·d)) | **≈ 1.6×** |
Complexidade: o laço interno da op roda `k` vezes por `(passo, canal)` ⇒ `O(k)` para o scan;
o backward recomputa os estados (`O(k)`) e faz `k` passes de propagação ⇒ `O(k)`.
O custo **não** é exatamente `2×` porque há overhead fixo (alocação dos tensores de saída
`(b,n,k,d)`, do gradiente, do `cat`/`contiguous` do empacotamento e da cópia do estado).
Medição com ruído: a máquina é compartilhada (2 vCPU, outros agentes compilando no mesmo `CARGO_TARGET_DIR`);
as execuções acima são **medianas de 3 processos limpos**, e o pior caso observado chegou a `0.030 ms` (fwd, `k=2`).
**Memória:** a saída da op passa de `(b,n,d)` para `(b,n,k,d)` (fator `k` na ativação do scan) e o
backward materializa `O(b·d·k·(n+1))` floats de estados recomputados. Para `k = 2` isso é ~2× a
ativação do slot — relevante para o orçamento de memória do tronco (o SSD é 1 de 6 camadas).
---
## 8. Limitações e achados
### 8.1 Limitações desta implementação
1. **CPU apenas.** A op implementa `cpu_fwd`; `cuda_fwd`/`metal_fwd` não existem (o scan legado do v0.2.0
também não tinha) — em GPU, `apply_op3` erro. O tronco KHTST_RUST roda em CPU de todo modo.
2. **Sequencialidade.** O scan é estritamente causal (`t` crescendo) e não paraleliza por passo; o paralelismo
é por canal/lote (BUG-M7 preservado: uma op para o lote inteiro).
3. **`η` independente do tempo.** `η^{(k)}_j` é parâmetro por ordem e canal (não função de `x_t` nem de `t`).
O enunciado escreve `η_t^{(k)}`; a parametrização é a mais simples que preserva "learnable, por canal",
e o `t` na notação é vacuous nessa leitura. Uma porta *função de `x_t`* (tipo `σ(W_η x_t)`) seria
uma extensão natural (a op já aceita `η` por canal e por tempo — bastaria passar um tensor `(b,n,d,k)`).
4. **O `k` é global do bloco.** Não há mixture-of-orders: o slot usa a ordem `k` inteira. O
`fwd_ordens` expõe todas as ordens para que o agente H possa, por exemplo, projetar a ordem 1 e a ordem 2
separadamente.
5. **Forma fechada do Teo S-3 corrigida** (ver §3): a implementação satisfaz o Teo S-3 **corrigido**; a forma
literal do enunciado corresponde a outra convenção e a discrepância está quantificada e testada.
6. **Validação por FD no nível do bloco é impossível** pelo motivo de §8.2 (não por defeito do r-13).
7. **Sem CUDA/GPU, sem `f64`.** Tudo em `f32` (o repo é `f32`); as tolerâncias (`5e-3`) são as do padrão do repo.
### 8.2 ⚠ Achado PRÉ-EXISTENTE e grave (fora do escopo do r-13 → reportado ao orquestrador)
`src/camadas.rs`:
```rust
impl RmsNorm {
pub fn fwd(&self, x: &Tensor) -> Result<Tensor> {
rms_norm(x, self.ganho.as_tensor(), self.eps as f32) // candle_nn::ops::rms_norm
}
}
```
No **candle-nn 0.11**, `ops::rms_norm` é:
```rust
pub fn rms_norm(xs: &Tensor, alpha: &Tensor, eps: f32) -> Result<Tensor> {
...
xs.apply_op2_no_bwd(alpha, &RmsNorm { eps }) // ← SEM BACKWARD
}
```
e o `CustomOp2` `RmsNorm` do candle-nn 0.11 **não implementa `bwd`**. Consequência: **o gradiente é
cortado em toda normalização RMS do tronco** — o gradiente wrt a *entrada* da normalização (e o do seu
ganho `γ`) é silenciosamente descartado. Verificado experimentalmente: com `L = Σ rms_norm(x)`, o mapa de
gradientes **não contém** a entrada `x` (`gs.get(&x) == None`).
Efeitos:
* o caminho `x → norm1 → (porta_a, proj_x) → scan → proj_o → norm2 → FFN` **não propaga gradiente**;
sobra apenas o caminho residual (`x2 = x + proj_o(y)`);
* por isso a validação por diferenças finitas do gradiente de `ξ` **no nível do bloco** é impossível
(o gradiente analítico é "truncado" no `norm2`, o FD não é) — a validação do r-13 foi feita no nível
da **op** (grafo completo) e da cadeia `ξ → η → scan`;
* **o `tronco.rs` inteiro treina com gradiente parcial** — isso é um achado de auditoria de primeira ordem,
independente do r-13, e **não** foi corrigido aqui (o arquivo não é meu).
Correção possível (para quem for dono de `src/camadas.rs`): reimplementar o `RmsNorm` com ops
diferenciáveis do candle, em vez de `candle_nn::ops::rms_norm`:
```rust
let rms = x.sqr()?.sum_keepdim(candle_core::Dim::Minus1)?.affine(1.0 / d as f64, 0.0)?
.sqrt()?.affine(1.0, self.eps as f64)?;
x.broadcast_div(&rms)?.broadcast_mul(self.ganho.as_tensor())
```
(tudo isso é `Op` com backward correto no candle 0.11).
### 8.3 Notas de integração para o agente H
* `BlocoSsd::novo(d, d_ff, dev)` continua funcionando (`k = 1`); para `k = 2` use
`BlocoSsd::novo_com_ordem(d, d_ff, 2, dev)`.
* O `tronco.rs` **não precisa ser editado**; apenas a ponte Python que aloca o cache de inferência precisa
usar `(b, d, k)` quando `k ≥ 2`.
* `xi_eta` entrou em `BlocoSsd::vars()` ⇒ o otimizador o treat como parâmetro aprendível automaticamente.
* `eta_max` é campo público (default `1.0`); reduzir o valor limita mais a magnitude do estado;
`eta_max = 0` degenera no SSD clássico (η ≡ 0) com `k` qualquer.
---
## 9. Resumo em 5 linhas
1. `src/ssd.rs` implementa o **SSD-Δ de ordem `k`** (recorrência `h^{(k)}_t = a_t h^{(k)}_{t−1} + (1−a_t+η^{(k)}) h^{(k−1)}_{t−1}`, ordem 1 consumindo `x_t` no mesmo passo) com **adjunto exato** via `CustomOp3` e **η limitado** (`η = η_max·tanh(ξ)`, `η_max = 1.0`).
2. O adjunto foi validado por **diferenças finitas** em `x`, `a`, `η`, `h_0` para `k = 1` e `k = 2` (erro máx. `1.0e-3` < `5e-3`) e o `k = 1` é **bit-a-bit idêntico** ao scan legado (90/90 valores).
3. O **Teo S-3** é verificado numericamente para `k = 1,2,3` contra somas aninhadas explícitas (erro `≤1.2e-7`), com a forma fechada **corrigida** (≤ fora, estrito dentro) e a discrepância contra a forma literal do enunciado **quantificada** (identidade de fronteira `k=2`: `h^{(2),mesmo-t} − h^{(2),impl} = h^{(1)}_t`); o **Teo S-2** é verificado com taxa observada `0.900000` = cota `0.900000`.
4. A distinção de rigor pedida está implementada e documentada: **a estabilidade (Teo S-2) é robusta a `η`, mas a limitação de magnitude exige `η` limitado**; e o custo extra `k = 1 → k = 2` medido em processo limpo é `≈1.6×` no forward e no forward+backward (`0.018 → 0.026 ms` e `0.177 → 0.294 ms`, `b=4, n=1024, d=128`).
5. ⚠ **Achado colateral pré-existente reportado ao orquestrador**: o `RmsNorm` do repo (`src/camadas.rs`) usa `candle_nn::ops::rms_norm`, que no candle-nn 0.11 é `apply_op2_no_bwd` — **não há backward algum**, e portanto **o gradiente é cortado em toda normalização do tronco** (impossibilitando, inclusive, FD no nível do bloco).