# Ch357 ZSCHED integer-XY closeout

This note pins the persistent-Z ZSCHED signoff contract after the float-oracle mismatch was isolated.

## Contract

- The RTL renderer consumes integer screen coordinates from XYZ2. `gs_stub.sv` takes the integer X/Y fields and has no GS 12.4 subpixel raster path in this milestone.
- The ZSCHED fixture generator also emits integer XYZ2 coordinates via `quant_xy` before packing vertices. The subpixel geometry from the dump is not present in the feeder data.
- Therefore the signoff reference maps must use the same quantized XY vertices. For ZSCHED, `gs_make_sh3_scheduler_fixture.py` defaults `--authz --tag zsched` to integer-XY reference. Use `--float-ref-xy` only as a report-only fidelity-debt diagnostic.

Canonical fixture emit:

```sh
make -C sim sh3_zsched_fixture
```

Equivalent explicit command:

```sh
python3 tools/gs_make_sh3_scheduler_fixture.py \
  --draw-list 8634,12757,145742 --authz --tag zsched \
  --pscale auto,auto,384 --xy-quant round,round,round --ref-xy-quant --emit
```

## Current Gates

- `tb_top_psmct32_sh3_zsched` gates the integer-XY oracle at the documented 90% MULTI <=1 texel reciprocal floor.
- `tb_top_psmct32_sh3_zrop` replays the captured fragment trace through the clamp16 persistent-Z scoreboard.
- `tb_top_psmct32_sh3_zint` drives the real raster into the persistent-Z/color LPDDR path and gates zero fragment drops.
- `sh3_zsched_board_compare` regenerates the fragment trace and zint framebuffer dump, requires the pulled board framebuffer to match zint byte-for-byte, then replays emitted fragment colors through clamp16 GEQUAL and requires exact framebuffer color agreement.
- These three targets are now prerequisites of the default `make -C sim run`.

Measured integer-XY fixture result: ALL=20227/21645 (93.4%), MULTI=7111/7587 (93.7%), with `tb_top_psmct32_sh3_zsched` PASS. The old float-XY diagnostic stayed below the 90% MULTI floor because it compared against geometry that the hardware was not fed.

Measured board readback result from the refreshed fixture: `sh3_zsched_board_fb.mem` and `sh3_zsched_zint_fb.mem` both hash to `acd4076dfe3843a384f8fa885613484c5e62a9bbcbb5dff4d5bf78b168a22e2f`; `cmp` reports no byte differences. `--owner replay-color` also reports `53760/53760 (100.00%)` exact for both board and zint, with 50184 replayed fragments, 29937 Z-pass updates, and 21590 covered pixels.

## Board Readback

After a board dump:

```sh
sudo ./ps2_sh3_sched --zbuf sh3_zsched_epochs.txt --dump-fb sh3_zsched_board_fb.mem
scp terasic@192.168.50.161:~/sh3_zsched_board_fb.mem sim/data/top_psmct32_raster_demo/
python3 tools/gs_fb_to_png.py sim/data/top_psmct32_raster_demo/sh3_zsched_board_fb.mem \
  sim/data/top_psmct32_raster_demo/sh3_zsched_board_fb.png 256 210 3
make -C sim sh3_zsched_board_compare
```

Optional oracle diagnostic maps:

```sh
make -C sim tb_top_psmct32_sh3_zsched
python3 tools/analyze_zsched_fb.py sim/data/top_psmct32_raster_demo/sh3_zsched_board_fb.mem \
  --owner replay-color --frags sim/traces/rtl/zsched_frags.txt
python3 tools/analyze_zsched_fb.py sim/data/top_psmct32_raster_demo/sh3_zsched_board_fb.mem \
  --owner replay --frags sim/traces/rtl/zsched_frags.txt --maps
```

The `--owner replay` texture/refmap radius score and `sh3_zsched_board_fb_*oracle_*.png` images are diagnostic only. The hard hardware-vs-RTL readback gate is `make -C sim sh3_zsched_board_compare`; the hard emitted-fragment content check is `--owner replay-color`.