fix(bitnet): retire prefetch_done on entry to IDLE

[gHashTag]

The defect was still live on master

#1985 reports itself as fixed. Its fixes landed on a branch that never opened a PR, so the
defect is on master verbatim. Found at bootstrap/src/bitnet_buffers.rs:181-182:

s.push_str("            IDLE: if (start_prefetch) begin\n");
s.push_str("                state <= FETCH; prefetch_active <= 1'b1; prefetch_done <= 1'b0;\n");

DONE_ST raises prefetch_done and returns to IDLE; the only clear outside reset sits
inside the start_prefetch guard.

Why that is one cycle too late. The clear is a non-blocking assignment, so it takes
effect the cycle after the request is sampled. The consumer, multilayer_sequencer, does:

PREFETCH: begin start_prefetch<=1'b1; state<=WAIT_PF; end
WAIT_PF: if(prefetch_done) state<=RUN;

WAIT_PF tests the flag in the same cycle it holds start_prefetch high — exactly the one
cycle where the controller is still in IDLE and the stale 1 is still there.

The fix

Emit the clear in the IDLE arm ahead of the guard, so the flag is retired on entry to
IDLE and is genuinely the one-cycle pulse the module doc-comment already claimed:

IDLE: begin
    prefetch_done <= 1'b0;
    if (start_prefetch) begin
        state <= FETCH; prefetch_active <= 1'b1;
        ...
    end
end

No other signal, state or port changed. Scope: bootstrap/src/bitnet_buffers.rs, its
integration test, and one docs/now/ entry.

Three bars

TRUE

rustc --test bootstrap/src/bitnet_buffers.rs — the module is dependency-free, so its real
unit tests run standalone:

test result: ok. 23 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

ALIVE — the guard is not vacuous, and the obvious version of it would have been

The reset block also contains prefetch_done <= 1'b0;. Measured against the defective
emitter:

unanchored  v.contains("prefetch_done <= 1'b0;") = true
anchored    IDLE-arm clear-before-guard          = false

An unanchored contains check passes on the bug. The new guard therefore slices the IDLE
case arm out of the emitted text first and asserts the clear precedes the guard.

BITING — planted mutant

Mutant: move the clear back inside the start_prefetch branch (i.e. restore master).

test tests::prefetch_done_retired_in_idle_before_start_guard ... FAILED

thread 'tests::prefetch_done_retired_in_idle_before_start_guard' panicked at:
prefetch_done must be cleared on entry to IDLE, before the `if (start_prefetch)` guard,
so a new requester never observes the previous transaction's completion (#1985). IDLE arm:

            IDLE: if (start_prefetch) begin
                state <= FETCH; prefetch_active <= 1'b1; prefetch_done <= 1'b0;
                axi_araddr <= src_addr;
                words_remaining <= num_words;
                bram_addr <= 12'd0;
            end

test result: FAILED. 21 passed; 2 failed

The message prints the offending IDLE arm, which is what proves the assertion read the
right region rather than passing on the reset line. Reverting the mutant: 23 passed; 0 failed.

RTL evidence (icarus, on the actually-emitted Verilog)

Two transactions, sampling prefetch_done in the cycle the second start_prefetch is
raised — the cycle WAIT_PF looks at it:

emitter	sampled_done_t2	done_rises	we_count
master (defective)	1 — stale	2	4
this PR	0	2	4

done_rises=2 and we_count=4 are the controls: completion is still signalled exactly once
per transaction and all 2×2 words still reach the BRAM.

End-to-end, real multilayer_sequencer + real weight_prefetch_ctrl, two layers
(re-run against the sequencer as changed by #2337):

emitter	overlap_cycles	layer_start_during_prefetch
master (defective)	1	1
this PR	0	0

Layer 1 was starting compute while its own weights were still being written into the weight
BRAM. That is the overlap in the issue title.

The defect shipped under a green check

Master's own 22 unit tests all pass on the defective emitter (22 passed; 0 failed).

And they are not run in CI at all. No workflow invokes cargo test -p t27c;
corpus-ratchet.yml records that the step was removed by #2292 after going red on master
(1602 passed / 13 failed / 2 ignored). So the guards added here are proved locally and are
not executed by any required check. That gap is pre-existing and repo-wide — recorded here
rather than papered over, and deliberately not "fixed" in this PR, since the same comment
warns that re-adding it as a plain gate lands red and gets disabled.

Not fixed here, filed separately

#1985 reports a second defect: multilayer_sequencer uses a level-triggered handshake and
cannot distinguish "done already" from "done still". That is a different module
(bootstrap/src/bitnet_pipeline.rs) and a different change, so it is not bundled here.

The end-to-end measurement above shows this fix alone closes the observable overlap for that
consumer, but the handshake remains edge-insensitive by construction and is worth hardening
on its own. Filed as a follow-up rather than folded into this diff.

Notes

• Local pre-commit could not run: it calls scripts/tri check-now, which exits 1 with
  tri: t27c not found because no t27c binary is built in this worktree (the wrapper
  probes four paths, none present). That is a missing build artifact, not a policy
  violation. The gate's substantive assertion was verified instead by running the CI script
  itself, unmodified — scripts/ci/now-sync-gate-diff.sh — which needs no binary:
  NOW sync gate passed: docs/now/2026-08-21-prefetch-done-stale-flag.md (UTC window: 2026-08-20 .. 2026-08-22)

Closes #1985

[github-actions]

📓 NotebookLM Notebook linked to this PR

• Notebook ID: b83263109fb055dc
• URL: https://notebooklm.google.com/notebook/b83263109fb055dc

This notebook contains session context, decisions, and artifacts for this work.

[github-actions]

PR Dashboard

Generated at: 2026-08-21 15:48:14 UTC

• fix(bitnet): retire prefetch_done on entry to IDLE #2340 fix(bitnet): retire prefetch_done on entry to IDLE | Created: 2026-08-21 | Updated: 2026-08-21 | 17 failing / 25 total
• fix(bitnet): make the DMA local write strobe a pulse, not a level #2339 fix(bitnet): make the DMA local write strobe a pulse, not a level | Created: 2026-08-21 | Updated: 2026-08-21 | 17 failing / 25 total
• fix(tri_loop): damage-repair requires --snapshot instead of defaulting to a path nothing creates #2338 fix(tri_loop): damage-repair requires --snapshot instead of defaulting to a path nothing creates | Created: 2026-08-21 | Updated: 2026-08-21 | 19 failing / 22 total
• corpus: freeze the damage, patch one class at a time, and say where one rule stops #2161 corpus: freeze the damage, patch one class at a time, and say where one rule stops | Created: 2026-08-14 | Updated: 2026-08-21 | 0 failing / 9 total
• Unbreak FPGA CI and correct two unbacked hardware claims #2081 Unbreak FPGA CI and correct two unbacked hardware claims | Created: 2026-08-11 | Updated: 2026-08-20 | 5 failing / 27 total

Summary

Status	Count
Total Open PRs	5
PRs with Failing Checks	1
PRs with All Checks Green	4
READY	1
FAILING	1
PENDING	0

Seal Status

• ⚠️ STALE -- sha256(compiler.rs)=65f033d04125 != manifest seal=87e5cbd3ad94.
  The committed NMSE numbers were certified against an older compiler.rs.
  Run scripts/reseal-check.sh locally for the two-step reseal command (advisory; not a merge gate).