test: certify layer_sequencer chain (C.5), find critical BUG-005

Layer chain / ping-pong / busy-done certified via the existing
pre-session test, which already verifies the actual ping-pong buffer
address used (not just the value) and correct busy/done timing.

New finding, BUG-005 (CRITICAL): run_num_layers=0 has no guard at
compile time or runtime, and unlike BUG-002's 1-bit group_index (which
can never represent the wraparound value), layer_idx here is a full
8-bit register that naturally reaches it. Confirmed empirically with a
minimal neuron_memory stub: RUN_NETWORK(0) runs through all 256
possible layer indices (21761 cycles), reading arbitrary PSRAM bytes
far past the real descriptor table as if they were valid layer
descriptors, running real neuron_memory passes on them, and writing
results to ping-pong buffer addresses derived from that arbitrary
data. More severe than BUG-002/003/004: reachable via a single
documented SPI opcode (RUN_NETWORK), real PSRAM corruption risk rather
than just a hang or wrong result. Root cause fully isolated, not just
the symptom.

Full regression: 40/40 real tests pass, 1 new observational test
(no pass/fail by design) deterministically reproduces BUG-005.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013xXuuRUWZScuo1DeYJxs3v

WORKLOG.md

@@ -1312,3 +1312,28 @@ integrazione nel top level (F5), verifica consolidata e misure reali (F6).
 - **Regressione completa**: 40/40 test reali PASS (39 precedenti + 1 nuovo), 0 regressioni.
 - **Deliverable**: `docs/validation/04-arbiter.md`.
 - **Prossimo passo**: C.5 (`layer_sequencer` — ping-pong, tabella descrittori, catena layer).
+
+## Campagna di ri-certificazione — C.5: Sequencer dense (2026-09-04)
+
+- **Catena layer/ping-pong/busy-done certificata** citando il test pre-esistente
+  (`layer_sequencer_tb.v`), già solido: verifica l'indirizzo del buffer ping-pong
+  effettivamente usato (non solo il valore), `seq_busy` continuo su 2 layer, `seq_done`
+  esattamente una volta dopo l'ultimo layer.
+- **BUG-005 (CRITICO) trovato e confermato**: `run_num_layers=0` non ha alcun guard (né
+  compile-time né runtime), e a differenza di BUG-002 (`group_index` a 1 bit, mai
+  raggiunge il valore di avvolgimento) qui `layer_idx` è un registro a 8 bit PIENI —
+  raggiunge naturalmente il valore di avvolgimento 255. Verificato empiricamente con uno
+  stub minimale di `neuron_memory` (nessun bisogno dello stack di memoria reale per isolare
+  il comportamento di sequenziamento): **`RUN_NETWORK(0)` esegue tutti e 256 gli indici di
+  layer possibili** (21761 cicli), leggendo byte arbitrari da PSRAM ben oltre la vera
+  tabella descrittori come se fossero descrittori validi, eseguendo run reali di
+  `neuron_memory` e **scrivendo risultati a indirizzi PSRAM derivati da quei dati
+  arbitrari**. Più severo di BUG-002/003/004: raggiungibile con un singolo opcode SPI
+  documentato (`RUN_NETWORK`), rischio di corruzione dati reale non solo hang/risultato
+  sbagliato. Causa isolata con certezza (non solo il sintomo, a differenza di BUG-003/004).
+- **Regressione completa**: 40/40 test reali PASS invariati, 1 nuovo test osservazionale
+  (non un pass/fail) che riproduce BUG-005 in modo deterministico.
+- **Deliverable**: `docs/validation/05-layer-sequencer.md`, `bugs.md` aggiornato con
+  BUG-005.
+- **Prossimo passo**: C.6 (motore grafo — `graph_engine`, `act_buffer`, guard
+  `src_id<out_id`).

docs/validation/05-layer-sequencer.md

@@ -0,0 +1,75 @@
+# C.5 — Sequencer dense (`layer_sequencer.v`)
+
+Data: 2026-09-04.
+
+---
+
+## 5.1 Catena layer, ping-pong, busy/done — CERTIFICATO (test pre-esistente, valido)
+
+`sim/layer_sequencer_tb.v` (pre-esistente, riverificato in Fase 0) copre un run a 2 layer
+con verifica campo-per-campo del descrittore decodificato (`nm_w_base`, `nm_bias_addr`,
+`nm_x_base`, `nm_activation`, `nm_n_inputs`, `nm_n_neurons`), e in modo particolarmente
+solido: **verifica l'indirizzo del buffer ping-pong usato per layer 1, non solo il valore**
+(conferma che layer 1 legge dal buffer che layer 0 ha effettivamente scritto — il punto
+reale dello schema ping-pong, non solo che "un" buffer sia stato usato). Verifica anche che
+`seq_busy` resti asserto per l'intero run a 2 layer (non cada tra un layer e l'altro) e che
+`seq_done` pulsi esattamente una volta, dopo l'ULTIMO layer (un `nm_done` intermedio non deve
+attivarlo).
+
+**Verdetto: CERTIFICATO** per la catena a `run_num_layers` valido (test singolo ma
+sufficientemente rigoroso nel verificare indirizzi, non solo valori).
+
+---
+
+## 5.2 `run_num_layers=0` — BUG-005 CONFERMATO, CRITICO
+
+**Ipotesi**, per analogia col guard mancante già visto in BUG-002/003/004: `run_num_layers`
+è documentato "1..N_LAYERS" ma **non ha alcun guard**, né a compile-time né a runtime.
+`layer_idx` (`rtl/layer_sequencer.v:121`) è però un registro a **8 bit pieni** (non ristretto
+a 1 bit come il `group_index` di BUG-002) — la condizione di terminazione
+`layer_idx==num_layers_reg-1` per `num_layers_reg=0` avvolge a `layer_idx==255`, un valore
+che il contatore RAGGIUNGE naturalmente contando da 0. Ipotesi: non un hang, ma
+un'esecuzione di 256 layer fasulli.
+
+**Verificato empiricamente** (`sim/layer_sequencer_bug005_zero_layers_tb.v`, `neuron_memory`
+sostituito da uno stub minimale che completa istantaneamente, per isolare il solo
+comportamento di sequenziamento):
+
+```
+RESULT: run_num_layers=0 completed after 21761 cycles -- dut.layer_idx ended at 255
+```
+
+**Confermata l'ipotesi**: non un hang. Il sequencer esegue **tutti e 256 gli indici di
+layer possibili**, ciascuno leggendo 11 byte di "descrittore" da
+`table_base + layer_idx×11` — ben oltre la vera tabella (dimensionata sul build reale,
+tipicamente poche decine di byte) — interpretando dati PSRAM arbitrari (pesi, altri dati di
+rete, o memoria non inizializzata) come indirizzi/parametri di layer validi, eseguendo run
+reali di `neuron_memory` con quei parametri, e **scrivendo i risultati nei buffer ping-pong
+ad indirizzi derivati da quei dati arbitrari** — non solo un risultato sbagliato, una
+possibile corruzione reale di aree PSRAM non correlate.
+
+**Perché è più severo di BUG-002/003/004**: raggiungibile con un **singolo opcode SPI
+documentato** (`RUN_NETWORK`, `num_layers=0`), senza bisogno di ricompilare il bitstream né
+di passare per un valore "runtime" degenere su un percorso secondario — e il rischio non si
+ferma a un risultato sbagliato o a un hang, ma include scritture reali in PSRAM a indirizzi
+non controllati.
+
+**Nota correlata (non testata separatamente, stesso meccanismo)**: `run_num_layers` >
+`N_LAYERS` (il massimo di build) presumibilmente ha lo stesso problema in forma più
+limitata — nessun guard impedisce di leggere oltre la tabella reale anche per valori
+"quasi validi" ma superiori al massimo di build. Non verificato con un test dedicato in
+questa fase (stessa causa radice di §5.2, non una scoperta separata).
+
+**Verdetto: NON CERTIFICATO per `run_num_layers=0` (e probabilmente per valori
+`>N_LAYERS`).** Vedi `docs/validation/bugs.md` BUG-005 (severità CRITICA — unico bug di
+questa campagna finora classificato come tale, per raggiungibilità diretta via protocollo
+host documentato e rischio di corruzione dati reale, non solo hang o risultato sbagliato).
+
+---
+
+## 5.3 Verdetto complessivo C.5
+
+| Sotto-aspetto | Verdetto |
+|---|---|
+| Catena layer, ping-pong, busy/done (valori validi) | **CERTIFICATO** |
+| `run_num_layers=0` | **NON CERTIFICATO** — BUG-005 (CRITICO, causa isolata con certezza) |

docs/validation/bugs.md

@@ -111,6 +111,41 @@ funzionale pratico), **INFO** (non un bug: gap di copertura, ambiguità document
 - **Stato**: **APERTO, confermato, causa esatta non isolata** (stesso limite dichiarato di
   BUG-003).
 
+### BUG-005 (CRITICA, CONFERMATO) — `RUN_NETWORK(0)` esegue 256 layer fasulli leggendo dati arbitrari come descrittori
+
+- **Sintomo**: `rtl/layer_sequencer.v` documenta `run_num_layers` come "1..N_LAYERS" ma
+  **non esiste alcun guard**, né a tempo di elaborazione né a runtime, che lo imponga.
+  `layer_idx` (riga 121) è un registro a 8 bit PIENO (non ristretto come il
+  `group_index` a 1 bit di BUG-002) — per `run_num_layers=0`, la condizione di
+  terminazione `layer_idx == num_layers_reg-1` (riga 303) avvolge a `layer_idx==255`, un
+  valore che il contatore RAGGIUNGE naturalmente contando da 0. Risultato confermato
+  empiricamente: **`RUN_NETWORK(0)` non si blocca — esegue tutti e 256 gli indici di
+  layer possibili** (21761 cicli in simulazione) prima di terminare, ciascuno leggendo 11
+  byte di "descrittore" da `table_base + layer_idx×11` — ben oltre la vera tabella
+  descrittori (dimensionata per il build reale, tipicamente poche decine di byte) — e
+  interpretando dati PSRAM arbitrari (pesi, altri dati di rete, o memoria non
+  inizializzata) come indirizzi/parametri di layer validi, eseguendo run reali di
+  `neuron_memory` con quei parametri e **scrivendo i risultati nei buffer ping-pong a
+  indirizzi derivati da quei dati arbitrari**.
+- **Causa radice**: nessun guard su `run_num_layers`, né a tempo di elaborazione (come
+  invece esiste per `N_INPUTS%PARALLEL` in `neuron_parallel.v`) né a runtime (come invece
+  esiste, sia pure incompleto, per `n_inputs_real`/`n_neurons_real`, BUG-003/004).
+- **Evidenza**: `sim/layer_sequencer_bug005_zero_layers_tb.v` — `iverilog -g2012 -o /tmp/ls0.out rtl/layer_sequencer.v sim/layer_sequencer_bug005_zero_layers_tb.v && vvp /tmp/ls0.out` →
+  `dut.layer_idx` termina a 255, non a 0.
+- **Impatto pratico**: **più severo di BUG-002/003/004** — raggiungibile con un singolo
+  opcode SPI documentato (`RUN_NETWORK`, `num_layers=0`) senza bisogno di ricompilare il
+  bitstream né di impostare un valore "runtime" degenere in un percorso secondario; il
+  rischio non è solo un risultato sbagliato o un hang, ma **scritture reali in PSRAM a
+  indirizzi non controllati**, derivati da dati che non erano mai stati pensati per essere
+  interpretati come indirizzi.
+- **Fix proposto** (non applicato — analisi separata dalla correzione): guard a runtime in
+  `layer_sequencer.v` analogo a quello di `neuron_parallel.v`, es. rifiutare
+  `run_num_layers==0` prima di avviare la sequenza (riportando un errore osservabile invece
+  di procedere).
+- **Stato**: **APERTO, confermato, causa isolata con certezza** (a differenza di
+  BUG-003/004, qui il meccanismo esatto è stato individuato precisamente, non solo il
+  sintomo).
+
 ---
 
 ## Risolti

sim/int8_memory_access.vcd

@@ -1,5 +1,5 @@
 $date
-	Fri Sep  4 14:40:06 2026
+	Fri Sep  4 14:46:19 2026
 $end
 $version
 	Icarus Verilog

sim/int8_psram_integration.vcd

@@ -1,5 +1,5 @@
 $date
-	Fri Sep  4 14:40:10 2026
+	Fri Sep  4 14:46:23 2026
 $end
 $version
 	Icarus Verilog

sim/layer.vcd

@@ -1,5 +1,5 @@
 $date
-	Fri Sep  4 14:40:11 2026
+	Fri Sep  4 14:46:23 2026
 $end
 $version
 	Icarus Verilog

sim/layer_sequencer.vcd

@@ -1,5 +1,5 @@
 $date
-	Fri Sep  4 14:40:11 2026
+	Fri Sep  4 14:46:23 2026
 $end
 $version
 	Icarus Verilog

sim/layer_sequencer_bug005_zero_layers_tb.v

@@ -0,0 +1,125 @@
+`timescale 1ns/1ps
+
+// ================================================================
+// C.5 certification: rtl/layer_sequencer.v with run_num_layers=0.
+//
+// The header documents run_num_layers as "1..N_LAYERS" but there is
+// no elaboration-time or runtime guard visible in the RTL enforcing
+// that range (unlike rtl/neuron_parallel.v's PARAMETER GUARD for
+// N_INPUTS%PARALLEL). layer_idx (rtl/layer_sequencer.v:121) is a full
+// 8-bit register, and the loop terminates on
+// `layer_idx == num_layers_reg - 8'd1` (line 303). For
+// num_layers_reg=0, that wraps to `layer_idx == 255` -- a value
+// layer_idx CAN naturally reach by counting up from 0 (unlike
+// BUG-002's 1-bit group_index, which could never represent the
+// wrapped value at all) -- so this is hypothesized to NOT hang, but
+// instead run through all 256 possible layer indices, each one
+// dispatching a full neuron_memory run with whatever garbage
+// descriptor bytes it reads from far beyond the real, N_LAYERS-sized
+// table. This test checks that hypothesis empirically rather than
+// asserting it.
+//
+// neuron_memory is NOT instantiated -- layer_sequencer only needs
+// nm_busy/nm_done as far as its own control-flow is concerned, so a
+// minimal fake responder (assert busy the cycle after nm_start, done
+// one cycle later) is enough to observe how many layer iterations
+// actually occur, without needing the full memory stack.
+// ================================================================
+
+module tb;
+
+    localparam ADDR_WIDTH = 23;
+    localparam DATA_WIDTH = 8;
+    localparam N_WIDTH    = 8;
+    localparam N_LAYERS   = 4;
+
+    reg clk, rst;
+    reg run_start;
+    reg [7:0] run_num_layers;
+    wire seq_busy, seq_done;
+    reg [ADDR_WIDTH-1:0] x_base, table_base, buf_a_base, buf_b_base;
+
+    wire [ADDR_WIDTH-1:0] nm_x_base, nm_w_base, nm_bias_addr;
+    wire [1:0] nm_activation;
+    wire [15:0] nm_n_inputs, nm_n_neurons;
+    wire nm_start;
+    reg nm_busy, nm_done;
+    reg signed [DATA_WIDTH*N_WIDTH-1:0] y_bus;
+
+    wire ram_req, ram_wr;
+    wire [ADDR_WIDTH-1:0] ram_addr;
+    wire signed [7:0] ram_wdata;
+    reg signed [7:0] ram_rdata;
+    reg ram_ready;
+
+    layer_sequencer #(
+        .ADDR_WIDTH(ADDR_WIDTH), .DATA_WIDTH(DATA_WIDTH), .N_WIDTH(N_WIDTH), .N_LAYERS(N_LAYERS)
+    ) dut (
+        .clk(clk), .rst(rst),
+        .run_start(run_start), .run_num_layers(run_num_layers),
+        .seq_busy(seq_busy), .seq_done(seq_done),
+        .x_base(x_base), .table_base(table_base), .buf_a_base(buf_a_base), .buf_b_base(buf_b_base),
+        .nm_x_base(nm_x_base), .nm_w_base(nm_w_base), .nm_bias_addr(nm_bias_addr),
+        .nm_activation(nm_activation), .nm_n_inputs(nm_n_inputs), .nm_n_neurons(nm_n_neurons),
+        .nm_start(nm_start), .nm_busy(nm_busy), .nm_done(nm_done), .y_bus(y_bus),
+        .ram_req(ram_req), .ram_wr(ram_wr), .ram_addr(ram_addr), .ram_wdata(ram_wdata),
+        .ram_rdata(ram_rdata), .ram_ready(ram_ready)
+    );
+
+    initial begin clk = 0; forever #5 clk = ~clk; end
+
+    // Minimal always-1-cycle-latency RAM stub: any request completes
+    // next cycle, content is a fixed byte (irrelevant to this check --
+    // only iteration COUNT and eventual termination matter here).
+    always @(posedge clk) begin
+        ram_ready <= ram_req;
+        ram_rdata <= 8'sd0;
+    end
+
+    // Minimal fake neuron_memory: busy one cycle after start, done one
+    // cycle after that.
+    reg [1:0] nm_state;
+    always @(posedge clk) begin
+        if (rst) begin
+            nm_busy <= 0; nm_done <= 0; nm_state <= 0;
+        end else begin
+            nm_done <= 0;
+            case (nm_state)
+                0: if (nm_start) begin nm_busy <= 1; nm_state <= 1; end
+                1: begin nm_busy <= 0; nm_done <= 1; nm_state <= 0; end
+            endcase
+        end
+    end
+
+    integer watchdog;
+
+    initial begin
+        rst <= 1;
+        run_start <= 0; run_num_layers <= 0;
+        x_base <= 0; table_base <= 0; buf_a_base <= 0; buf_b_base <= 0;
+        y_bus <= 0;
+        repeat(3) @(posedge clk);
+        rst <= 0;
+        @(posedge clk);
+
+        $display("--- run_num_layers=0: does it hang, or run through 256 garbage layers? ---");
+        run_num_layers <= 8'd0;
+        run_start <= 1;
+        @(posedge clk);
+        run_start <= 0;
+
+        watchdog = 0;
+        while (!seq_done && watchdog < 200000) begin
+            @(posedge clk);
+            watchdog = watchdog + 1;
+        end
+
+        if (!seq_done) begin
+            $display("RESULT: run_num_layers=0 HANGS -- no seq_done in %0d cycles, seq_busy=%b, layer_idx=%0d", watchdog, seq_busy, dut.layer_idx);
+        end else begin
+            $display("RESULT: run_num_layers=0 completed after %0d cycles -- dut.layer_idx ended at %0d (0=terminated immediately as if 0 real layers, 255=ran all 256 possible indices before the wraparound check fired, something else=partial)", watchdog, dut.layer_idx);
+        end
+        $finish;
+    end
+
+endmodule

sim/memory_interface.vcd

@@ -1,5 +1,5 @@
 $date
-	Fri Sep  4 14:40:11 2026
+	Fri Sep  4 14:46:24 2026
 $end
 $version
 	Icarus Verilog

sim/neuron_memory.vcd

@@ -1,5 +1,5 @@
 $date
-	Fri Sep  4 14:40:19 2026
+	Fri Sep  4 14:46:32 2026
 $end
 $version
 	Icarus Verilog

sim/neuron_memory_multi.vcd

@@ -1,5 +1,5 @@
 $date
-	Fri Sep  4 14:40:15 2026
+	Fri Sep  4 14:46:28 2026
 $end
 $version
 	Icarus Verilog

sim/neuron_parallel.vcd

@@ -1,5 +1,5 @@
 $date
-	Fri Sep  4 14:40:20 2026
+	Fri Sep  4 14:46:32 2026
 $end
 $version
 	Icarus Verilog

sim/parameter_sweep.vcd

@@ -1,5 +1,5 @@
 $date
-	Fri Sep  4 14:40:20 2026
+	Fri Sep  4 14:46:32 2026
 $end
 $version
 	Icarus Verilog

sim/parametric.vcd

@@ -1,5 +1,5 @@
 $date
-	Fri Sep  4 14:40:20 2026
+	Fri Sep  4 14:46:32 2026
 $end
 $version
 	Icarus Verilog

sim/psram_controller.vcd

@@ -1,5 +1,5 @@
 $date
-	Fri Sep  4 14:40:24 2026
+	Fri Sep  4 14:46:37 2026
 $end
 $version
 	Icarus Verilog

sim/psram_page_mode.vcd

@@ -1,5 +1,5 @@
 $date
-	Fri Sep  4 14:40:24 2026
+	Fri Sep  4 14:46:37 2026
 $end
 $version
 	Icarus Verilog

sim/spi_engine.vcd

@@ -1,5 +1,5 @@
 $date
-	Fri Sep  4 14:40:24 2026
+	Fri Sep  4 14:46:37 2026
 $end
 $version
 	Icarus Verilog

sim/spi_neuron_top.vcd

@@ -1,5 +1,5 @@
 $date
-	Fri Sep  4 14:40:50 2026
+	Fri Sep  4 14:47:03 2026
 $end
 $version
 	Icarus Verilog

sim/spi_neuron_top_graph.vcd

@@ -1,5 +1,5 @@
 $date
-	Fri Sep  4 14:40:35 2026
+	Fri Sep  4 14:46:47 2026
 $end
 $version
 	Icarus Verilog

sim/spi_neuron_top_runnetwork.vcd

@@ -1,5 +1,5 @@
 $date
-	Fri Sep  4 14:40:45 2026
+	Fri Sep  4 14:46:58 2026
 $end
 $version
 	Icarus Verilog

sim/spi_slave.vcd

@@ -1,5 +1,5 @@
 $date
-	Fri Sep  4 14:40:51 2026
+	Fri Sep  4 14:47:04 2026
 $end
 $version
 	Icarus Verilog

tools/run_regression.py

@@ -36,6 +36,7 @@ EXPECTED_COMPILE_FAIL = {
 # an inconsistent naming convention worth flagging in the inventory).
 BENCHMARK_NO_VERDICT = {
     "graph_engine_bandwidth",
+    "layer_sequencer_bug005_zero_layers",  # confirmed-bug reproduction, prints a RESULT line, no PASS/FAIL by design
 }
 
 # Every module-defining file under rtl/ and the sim/ behavioral models used