Snake (M27): lean ray-cast observation + net-guided multi-ply search — food@12 ~21 → ~78.6

[PieterjanDeClippel]

Summary

Makes the Snake demo AI substantially stronger by combining two changes, in line with the M27 goal of pushing toward 100 food on the 12×12 grid:

1. Lean ray-cast observation (already on this branch): replaced the myopic 9×9 egocentric patch (177 inputs, mostly zeros) with 8-direction ray-cast vision — per ray: food-on-line, 1/dist-to-body, 1/dist-to-wall — plus flood-fill, food/tail bearing+distance, heading, and length. ObservationSize 177 → 39, grid-size-invariant. A reactive DQN on this obs tops out at ~50 food (vs the old net's ~21), confirming the reactive plateau is structural.

2. Net-guided multi-ply look-ahead (SnakeSearchAgent) — the EfficientCube idea of searching on top of a learned value function, applied to Snake. Snake is deterministic between food (the food RNG lives in the env's saved state), so look-ahead is exact: the agent simulates every legal line ~20 plies deep on a private env clone (SaveState/RestoreState), scores each leaf by flood-fill survivability (the new SnakeEnv.FreeSpaceAhead, a hard self-trap penalty) + food eaten + the trained net's value + tiebreaks, and plays the first move of the best line. The net is the leaf evaluator — genuinely net-guided, not brute force.

Result: food@12 ≈ 78.6 — 3.7× the original 21, ~1.6× the reactive net, from the same trained net amplified by search.

What the sweep found

• Depth is the lever — 65 (d6) → 71 (d10) → ~79–84 (d20); d28/d36 give no reliable gain (deep lines get misranked under beam pruning). d20 is the sweet spot.
• Wider beam hurts (keeps greedy food-grabs that trap later); space-weight helps then saturates; net weight is marginal (the survival search carries it — the forward is skipped when its weight is 0).
• Starvation window is not the cap — widening it 2→4→8 saturates at ~80. The residual cap is self-traps that form beyond the horizon.

Changes

• SnakeEnv: + FreeSpaceAhead (look-ahead survivability), + configurable starveLimitCells (training stays tight; inference can widen). Lean 39-dim ray-cast observation.
• SnakeSearchAgent / SnakeSearchOptions (new) + SnakeSearchAgentTests (beats greedy with the same net, deterministic, always legal).
• Lab eval: --search/--depth/--beam/--w-food/--w-trap/--w-net/--w-space/--starve.
• SnakeModelService exposes the net; SnakeController.Live drives the demo via the planner.
• models/snake.dqn.ckpt → the lean 39-dim net (the old 177-dim net is incompatible with this obs; net + SnakeEnv ship together so the fix(web): Snake 'stream closed' — refresh shipped checkpoints + reject incompatible net #10 InputSize guard stays satisfied).
• Environments package bumped 0.2.0 → 0.3.0 (new public API).
• PRD §14 + PLAN M27 updated.

Testing

• 269/269 fast tests pass; all Snake tests pass (fast + the slow campaign-contract tests).
• One unrelated slow training-threshold gate for another game failed in the full slow run (a known-noisy class; outside the Snake changes — the diff touches no non-Snake training code). Worth a confirming re-run before merge.

Honest ceiling / follow-up

Reaching a clean 100 needs a tail-reachability survival invariant (guarantee the head can always reach its own tail → follow it indefinitely) and/or explicit Hamiltonian-style endgame play. Not built here — proposed as the next step.

🤖 Generated with Claude Code