HP.3: snap leave-angles onto distinct grid headings

[grootstebozewolf]

Stacked on #29 (cursor/hp2-curve-hotpixel-5bb4 @ 784f3c25). Sibling of P2.5.5, not the 74-file blast. Do not merge into #7 / feature/sfa-curve-rgr. Do not restack onto #27 / #28.

This is the HotPixel ladder. HP.0 / HP.1 / HP.2 done. This is HP.3 only.

Name is OverlayNGCurve, never OverlayNGCurved (NTSC0001).

What HP.3 is

A package-private snap next to CurveHotPixel in org.locationtech.jts.operation.overlayng.curve. CurveHotPixel stays a pixel test (intersects + exit). CurveHotPixelSnap turns a leave's pixel-exit into a discrete heading.

Heading key: integer (dx, dy) in the scaled lattice. The circle–square / arc–AABB exit is rounded with Math.round (half-up, same family as HotPixel scale-round) and subtracted from the already-rounded node. Two leaves have distinct headings iff the keys differ. (0, 0) is not a heading. Documented miss (null) when the string does not intersect the pixel or does not start in it.

Do not snap the shared tangent. Both H-SHELL-N-ODD leaves at (0, 5) are still +x (ANGLE_EPS = 1e-8). Snap the arc exit, not the supporting chord.

Outcome at scale 10: shared ray, stamp

Investigated; not prescribed.

Pixel at (0, 5), scale 10, width 0.1, half-open (left/bottom closed, top/right open). Both leaves start at the node and exit the open right side:

leave	arc exit (approx.)	snapped lattice	key
HALF_DISC (0,5)→(5,0)	(0.05, 4.99975)	(1, 50)	(1, 0)
STADIUM_ODD (0,5)→(1,4)	(0.05, 4.99875)	(1, 50)	(1, 0)

They share one snapped grid point. HP.3 stamps SHARED_SNAPPED_RAY ("HP.3 shared snapped ray") and stops. Same stop rule as P2.5.4. No curvature-order tie-break (HP.1 already refuted that: 18.42 vs pair-kit 13π+2).

The unsnapped faces path is unchanged: testN3TangentStampsNull and testCurvatureOrderWalksWrongRings stay bit-identical (missReason == TANGENT_LEAVE_ANGLE). The new stamp is not wired into faces.

Pins

1. Unsnapped leaves still coincident (leaveAngle still +x).
2. Supporting chords (HALF_DISC diameter y=0, STADIUM_ODD cap y=4) have no heading. Exit y stays near 5, not those chords.
3. Both snapped keys are (1, 0) — shared ray, stamp.
4. HALF_HANGING (HP.2 miss) has no heading. No invented key.

What this is not

• Not HP.4 (faces after snap). Do not walk.
• Not HP.5 / P2.5.5 / core HotPixel / ScaledNoder / SnapRoundingNoder / RobustLineIntersector / SegmentString.
• Not a circular noder.
• Not densify-then-snap flagged isApproximate()=false.
• Not intersectsScaled on a chord standing in for an arc.
• Does not loosen t_laser ≤ 1.15 × t_chainsaw (no overlay laser on this card).

Never list (catalog)

• curvature-order walk (already refuted, HP.1)
• replace TANGENT_LEAVE_ANGLE on the unsnapped faces path
• edit org.locationtech.jts.noding.snapround / core HotPixel.java
• start HP.4 / HP.5 / P2.5.5
• merge into feature/sfa-curve-rgr / PR SFA/SQL-MM curve awareness: Curve rename, arc-aware operations, OverlayNGCurve ratchet (#1195 RGR series) #7

Verify

Same suite as #29. Slack 15% (unchanged). OverlayNGCurve never Curved. All green after this revision:

• CurveSegmentStringTest 32 / 0 (HP.1 + P2.5.4 stamps unchanged; four HP.3 pins added)
• CompoundCurveShellOverlayTest 27 / 0
• CircularArcOverlayTest 11 / 0
• CircularDiscOverlayTest 12 / 0
• CircularDiscPolygonOverlayTest 7 / 0
• CircularLineOverlayTest 7 / 0
• OverlayNGCurvePhase0Test 19 / 0
• OverlayNGCurveRatchetTest 50 / 0
• OverlayNGCurvePerfGateTest 82 / 0 (15% slack)
• Naming-guard OK; Checkstyle 0 violations; PMD check on jts-curve succeeded

mvn -pl modules/curve -am test -DfailIfNoTests=false -Dcheckstyle.skip=true -Dpmd.skip=true \
  -Dtest=CurveSegmentStringTest,CompoundCurveShellOverlayTest,CircularArcOverlayTest,CircularDiscOverlayTest,CircularDiscPolygonOverlayTest,CircularLineOverlayTest,OverlayNGCurvePhase0Test,OverlayNGCurveRatchetTest,OverlayNGCurvePerfGateTest
bash dev/check-no-curved.sh
mvn -pl modules/curve checkstyle:check
mvn -pl modules/curve pmd:check

git diff vs #29 touches only modules/curve (CurveHotPixel, CurveHotPixelSnap, CurveSegmentStringTest). Core HotPixel.java and org.locationtech.jts.noding.snapround were not edited. HP.4 / HP.5 / P2.5.5 were not started.