bug(latent): spider.ts encodes hunt tile key with hardcoded <<7 instead of SURFACE_GRID_WIDTH

[LightAxe]

Location

src/sim/spider.ts lines ~93 and ~109

Description

findHuntTarget encodes and decodes hunt tile keys using a hardcoded 7-bit shift:

const key = (ay << 7) + ax;   // encode
bestX = k & 127;               // decode ax
bestY = k >> 7;                // decode ay

The inline comment acknowledges the assumption: // ay * SURFACE_GRID_WIDTH(128) + ax; 128 = 2^7.

tile-key.ts imports SURFACE_GRID_WIDTH from constants.ts and derives its stride constant from it:

import { SURFACE_GRID_WIDTH } from './constants.js';
const TILE_KEY_STRIDE = SURFACE_GRID_WIDTH;

spider.ts does not — it hardcodes 128 = 2^7 directly.

Impact

Currently benign: SURFACE_GRID_WIDTH = 128 and 128 = 2^7. If SURFACE_GRID_WIDTH is ever changed (e.g. a larger map config), spider.ts silently computes wrong tile coordinates from the packed key. The spider would evaluate ant density at incorrect tiles, misidentifying hunt targets. No compile-time error, no assertion failure, no test failure — silent wrong behaviour.

Fix

Replace the literal shift with a constant derived from SURFACE_GRID_WIDTH, or use the same TILE_KEY_STRIDE approach as tile-key.ts. Add a compile-time assertion (as tile-key.ts does for its own encoding) so future changes to SURFACE_GRID_WIDTH cause a build error here rather than a silent bug.

Severity

Medium — latent bug, currently safe, no behavioural change until map dimensions change.

[LightAxe]

Reviewed against current origin/main (16e4201) and this is legitimate as a latent correctness bug.

spider.ts already imports SURFACE_GRID_WIDTH/SURFACE_GRID_HEIGHT and sizes HUNT_TILE_COUNTS from them, but findHuntTarget still encodes/decodes with 128-specific bit math:

• src/sim/spider.ts:93: (ay << 7) + ax
• src/sim/spider.ts:108: k & 127
• src/sim/spider.ts:109: k >> 7

That is currently safe only because SURFACE_GRID_WIDTH === 128. If the width changes, this will silently choose wrong hunt target coordinates while the backing array size changes correctly.

One caveat on the obvious fix: because this is src/sim, replacing k >> 7 with ordinary / SURFACE_GRID_WIDTH would likely trip the sim division lint. The cleaner fix is probably to stop decoding the packed key at all: when a tile first becomes dirty, also retain its ax/ay in reusable scratch arrays or store the best ax/ay as part of the scan. If we want to preserve the bit-packed form, add an explicit assertion/test that spider hunting only supports width 128 so the invariant is honest.

[LightAxe]

Agree — latent bug, but the fix needs care in src/sim/ due to the division lint rule.

Verified against origin/main (16e4201). spider.ts imports SURFACE_GRID_WIDTH and uses it to size HUNT_TILE_COUNTS, but findHuntTarget still hardcodes the 7-bit shift for encode/decode at lines 93, 108, 109.

Agree with Codex's division-lint concern: replacing k >> 7 with k / SURFACE_GRID_WIDTH would trip the sim float-division rule, so that's not a valid fix.

Proposed fix: define a named log2 constant const HUNT_KEY_SHIFT = 7 alongside a compile-time assertion if (SURFACE_GRID_WIDTH !== (1 << HUNT_KEY_SHIFT)) throw new Error(...) — same pattern as tile-key.ts's _SURFACE_WIDTH_IS_128 guard. This makes the assumption explicit and loud rather than silent. The encode/decode lines keep the bitwise math (no division), but now reference the named constant and fail fast at startup if the width changes. No behavior change.

[LightAxe]

Resolved by PR #167 (squash-merged to main as 73d6d64).