Expose per-event flow to ARM via AXI4-Lite FLOW bundle (ENTR-31)

[davidshukhin]

Closes the last open item of SYSTEM_ANALYSIS.md / ENTR-31: the ARM's read_flow_vectors() read from a register space the FPGA never wrote — the collision predictor was running on dummy data, and the read would have indexed past the 128-word sim register file.

Design

• New s_axilite FLOW bundle: flow_out[2048] (first 1024 events × 2 words), flow_count, and a seqlock flow_seq written last so the ARM detects reads that straddle an export and retries.
• Word format per entry i: +8i → x/y as UQ4.12 (true normalized ring-buffer coords), +8i+4 → vx/vy as Q8.8 from flow_pred.
• Bounded at 1024 entries: full 4096 would need a 32 KB AXI4-Lite window and ~8k single-beat PS reads per 100 Hz frame; the ARM clusterer needs 30–50 events per object.
• Index mapping flow_pred[i] ↔ ring_buffer_events[(read_ptr+i) & RB_ADDR_MASK] is sound because no ingest occurs between NORMALIZE and COMPUTE_EVASION.

Changes

• fpga/top_level.cpp: FLOW_EXPORT loop (II=2) + pragmas; fpga/build.tcl mirror directives
• arm/fpga_interface.h (new): FpgaInterface extracted from drone_main.cpp; seqlock decode; stale REG_FLOW_PRED_BASE float-memcpy scheme deleted
• fpga/hls_compat.h: Vitis-compatible range(hi, lo) on the sim fixed-point types
• Tests: test_flow_export in the C testbench (bit-exact cross-check against the DEBUG bundle) + ARM register round-trip, end-to-end TTC from register-decoded flow, clamping edge cases
• Docs: FLOW register map + read protocol in fpga/README.md; SYSTEM_ANALYSIS item 10 marked FIXED

Validation

• make test-fpga: 22/22 (incl. new flow-export assertions)
• make test-arm: 29/29 (incl. 6 new round-trip tests)
• clang-format clean
• ⚠️ AXI offsets (0x10/0x18/0x2000 @ 0x43C1_0000) follow standard Vitis allocation but are to-be-confirmed against the generated _hw.h when ENTR-13's real synthesis runs — flagged in code + README.