Measure coastal frames' sea surface: an elevation, not an error (#65)

[NewGraphEnvironment]

Summary

• No behaviour change. fly#65's premise — MRDEM's ~0.14 m near-shore sea is an error — was measured before any remedy was built. Over water the sea is the imaged surface. A ray-cast of the true footprint on bare earth (1,242 coastal frames) shows the package's land-and-sea mean (W) is closer on area (0.34% vs 0.67% of width), while the land-only mean (L) is closer on the land edge (3.67% vs 4.43% of land misplaced). The pre-registered pooled test found no remedy warranted.
• Two qualifications, recorded not acted on: matched for relief, the sea does worsen W's land edge (not its area); and a canopy can reverse the area verdict (first-order; package-wide, filed as Footprints are sized from bare earth, but over forest the camera sees the canopy #80).
• Adds data-raw/dem_measure-coastal_water.R (ray-cast with flat and step synthetic controls, stratified sample of 240 runs), ships inst/extdata/dem_coastal_*.csv, and tests/testthat/test-fly_footprint_coastal.R rebuilds every table in the new note section row by row. Retracts the fly#58 "Ocean" bullet; adds a fly#65 section to inst/notes/terrain-correction.md; NEWS, CLAUDE.md, roxygen.

Related Issues

• Closes A coastal frame is sized from sea level and reports full DEM coverage #65
• Filed Footprints are sized from bare earth, but over forest the camera sees the canopy #80 (canopy vs bare-earth DEM)

Decision for review

Relief-matched, W misplaces more coastal land than inland. The rule fixed before the run tested pooled, and passed. Whether to act is a schema decision:

1. Ship as is, docs only (this PR) — recommended; W stays right for area, which is what coverage sums, and a land-edge remedy needs its own design (a per-side rectangle recovers only 16% of the edge error).
2. Add a sea/land-fraction column so callers testing a land AOI can flag mostly-sea frames.
3. Offer a land-only sizing option for land-edge use.

Test plan

• devtools::test() — 2,691 pass, 0 fail
• Note tables mutation-checked: changing one figure in any rebuilt row fails the suite
• Measurement deterministic: three runs re-measured, CSVs byte-identical
• /code-check — 4 rounds, ended by an enumeration of 136 published claims (no wrong figure)
• CI (R-CMD-check, pkgdown)

Notes

Rule history is in planning/archive/2026-09-issue-65-coastal-sea-surface/: the decision rule, two amendments made before any frame was measured (the planned spacing instrument measures shutter timing, not coverage), and every correction the reviews forced.

🤖 Generated with Claude Code

https://claude.ai/code/session_0115csb82i78r86GWFzwPzis