Checkpoint JPEG-LS hardening and logs

Bundle SCAN_ROWS=64 RTL updates, refreshed CharLS reference streams, and a tracked checkpoint log with regression and quick-synth results.

Includes FSM safe-state hardening, control-path cleanup, and the latest quick synthesis snapshot on xc7vx690tffg1761-2.

docs/jls_checkpoint_2026-04-17.md

@@ -0,0 +1,124 @@
+# JPEG-LS Checkpoint 2026-04-17
+
+## Scope
+
+This checkpoint bundles the current `SCAN_ROWS=64` RTL, the updated CharLS
+reference codestream set, and the latest reliability-oriented hardening work:
+
+- discrete `NEAR` coding-parameter / preset-parameter lookup tables
+- strip-start staging between `jls_scan_ctrl` and top-level launch consumers
+- reconstruction-wrap constant precompute (`RANGE_SCALE`)
+- neighbor/history and header-path timing splits
+- FSM safety hardening for the major control state machines
+- cleanup of dead internal signals and ignored-interface plumbing
+
+## Reliability Hardening
+
+Safe-state synthesis attributes were added to the following state machines:
+
+- `fpga/verilog/jls_golomb_encoder.sv`
+- `fpga/verilog/jls_header_writer.sv`
+- `fpga/verilog/jls_mode_router.sv`
+- `fpga/verilog/jls_regular_error_quantizer.sv`
+- `fpga/verilog/jls_run_mode.sv`
+- `fpga/verilog/jpeg_ls_encoder_top.sv`
+
+Additional hardening / cleanup in this checkpoint:
+
+- state return guard added for `jls_run_mode.state_after_run_code`
+- dead internal signals removed from `jls_neighbor_provider`, `jls_context_model`
+- ignored top-level / spare inputs are now explicitly observed where needed to
+  avoid ambiguous synthesis behavior
+- `jls_output_buffer` no longer carries meaningless reserved input ports
+
+## Functional Regression
+
+### Basic smoke tests
+
+Executed without rerunning the full pattern regression:
+
+- `tb_jls_header_writer`: PASS
+- `tb_jls_context_update`: PASS
+- `tb_jpeg_ls_encoder_top_run_smoke`: PASS
+- `tb_jpeg_ls_encoder_top_run_smoke` 8-bit two-strip ratio=2 case: PASS
+- dynamic-NEAR validation on `rtl_top_ramp_8b_2strip_ratio2.jls`: PASS
+
+Observed dynamic-NEAR result for the 8-bit two-strip ratio=2 smoke:
+
+- frame count: `2`
+- `NEAR` sequence: `16 / 32`
+- overall max abs diff: `32`
+- target ratio check: PASS
+
+### Full pattern regression status carried forward
+
+Current `SCAN_ROWS=64` full pattern regression summary:
+
+- ratio `1:1`: `17 PASS / 0 FAIL`
+- ratio `2:1`: `16 PASS / 1 FAIL`
+- ratio `4:1`: `14 PASS / 3 FAIL`
+- ratio `8:1`: `13 PASS / 4 FAIL`
+
+Known target-ratio misses from the carried-forward regression set:
+
+- `2:1`
+  - `omaha-w6144-h256-s0-b16`
+- `4:1`
+  - `omaha-w6144-h256-s0-b16`
+  - `sena-w6144-h256-s0-b16`
+  - `sensin-w6144-h256-s0-b16`
+- `8:1`
+  - `omaha-w6144-h256-s0-b16`
+  - `sena-w6144-h256-s0-b16`
+  - `sensin-w6144-h256-s0-b16`
+  - `sinan-w6144-h256-s0-b16`
+
+## Quick Synthesis
+
+### Configuration
+
+- tool: Vivado 2023.2
+- part: `xc7vx690tffg1761-2`
+- top: `jpeg_ls_encoder_top`
+- clock target: `4.000 ns` (`250 MHz`)
+- mode: out-of-context quick synthesis
+
+### Result
+
+- WNS: `-0.677 ns`
+- estimated Fmax: about `215.2 MHz`
+
+### Current worst path
+
+Latest quick-synth worst path after the reliability-hardening changes:
+
+- source: `context_model_i/context_model_idle_reg_reg`
+- destination: `run_mode_i/FSM_hamming2_state_reg[*]/CE`
+- logic levels: `11`
+
+This means the earlier very deep generic control/data paths were eliminated, but
+the current worst case is still above the earlier temporary `<=7` goal after
+FSM-safe encoding was enabled.
+
+### Resource snapshot
+
+- Slice LUTs: `25949`
+- Slice Registers: `8713`
+- Block RAM Tile: `3.5`
+- DSP: `6`
+
+## Synthesis Notes
+
+The latest quick synthesis run reported:
+
+- `0` errors
+- `0` critical warnings
+- `32` warnings
+
+Important observation from the Vivado log:
+
+- safe-state handling was implemented for the hardened FSMs
+
+Residual warnings are now dominated by synthesis hygiene items rather than
+functional blockers.  The current checkpoint stops here intentionally without
+more timing optimization or compression-ratio tuning.

docs/jls_module_interfaces.md

@@ -32,7 +32,7 @@ Parameters:
 | `DEFAULT_PIC_ROW` | 256 | Default image height used when runtime dimensions are invalid. |
 | `MAX_PIC_COL` | 6144 | Maximum supported runtime image width. |
 | `MAX_PIC_ROW` | 4096 | Maximum supported runtime image height. |
-| `SCAN_ROWS` | 16 | Number of source rows in one standalone JPEG-LS strip frame. |
+| `SCAN_ROWS` | 64 | Number of source rows in one standalone JPEG-LS strip frame. |
 | `MAX_NEAR` | 31 | Maximum dynamic NEAR value. |
 | `OUT_BUF_BYTES` | 8192 | Internal byte output buffer size. |
 | `OUT_BUF_AFULL_MARGIN` | 256 | Input pause margin for the internal output buffer. |