Code review P5: polish — branch-encoding edge cases, graphics file validation, format docs, type hints

[HansGR]

Fifth and final stacked code-review PR (by Anthropic Fable 5.0). Based on the P4 PR — merge P1–P4 first. This tier's own commits are 66f5612..c4da72f.

What's included (4 commits)

• 66f5612 — LabelPointer branch-encoding edge cases. Two latent bugs in BRANCH_RELATIVE (no current branch hits them; verified by byte-identical builds): a branch distance of 0 fell through unhandled and encoded 0x00 instead of 0xff, and the range check was off by one on both ends — distance +128 (encodable as offset 127) was rejected while distance −128 (not encodable) was accepted and silently emitted as a forward branch. Both arms collapse to (distance − 1) % 256; the error message now reports the actual distance and valid range. Boundary tests added.
• a6a23e3 — size validation for palette/sprite/portrait files. A malformed .pal/.bin (e.g. a bad community sprite submission) previously flowed silently into the ROM data. PaletteFile/SpriteFile now require whole colors/tiles, and the seed-path portrait and palette loads (which had no size handling at all) require the exact size of the slot they replace, raising a ValueError that names the file. Character sprites keep their deliberate pad/truncate behavior. All shipped graphics files are well-formed, so output is unchanged. Tests added.
• 6005d31 — docs/SPRITE_FORMAT.md: the BGR15 color encoding, the SNES 4bpp planar tile packing (verified against the decoder in graphics/sprite_tile.py), expected file sizes, and the steps to add a custom sprite — so sprite authors no longer need to reverse-engineer the code.
• c4da72f — type hints (annotation-only) on the core surface newcomers hit first: Space/Reserve/Allocate/Free/Write/Read, Heap, Label/LabelPointer, seed.py, valid_rom_file.py, and the utils helpers. Python 3.9-compatible.

Seed compatibility

Verified byte-identical ROMs (SHA-256) against the pre-change baseline for four flagsets: default, 20-flag heavy, objectives, and a custom-graphics flagset (-cpal/-cpor) that specifically exercises the newly validated load paths. Full unit suite: 84 tests passing.

After this series

The review's one deliberately deferred item is refactoring the import-time side effects (args/log/objectives/battle-package ROM writes) into explicit initialization — documented in P4 and worth its own design discussion.

https://claude.ai/code/session_01QnF26DB2TYi1hpJE8L6EJr

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive unit test suite covering ROM-independent logic, improves error handling by replacing assertions with descriptive exceptions, and adds file size validation for graphics and palette files. It also refactors the objective conditions to share a common assembly-based implementation and fixes a branch relative offset calculation bug. A review comment identifies a high-severity issue in the newly rewritten truncated_discrete_distribution utility, where boundary checks are bypassed if minimum or maximum is set to 0 due to falsy evaluation.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

Using if minimum and if maximum to guard the boundary checks will fail if either limit is explicitly set to 0 (or 0.0), as 0 is falsy in Python. This causes the boundary check to be silently bypassed, potentially returning out-of-bounds values.

Instead, explicitly check if the limits are not None.

Suggested change

	if minimum and result < minimum:
	continue
	if maximum and result > maximum:
	continue
	if minimum is not None and result < minimum:
	continue
	if maximum is not None and result > maximum:
	continue