fl_cost_distance() seeds every zero-friction cell, not just stream cells

[NewGraphEnvironment]

Problem

fl_cost_distance() treats every zero-friction cell as a stream seed, not just stream cells.

# R/fl_cost_distance.R:51-52
cost <- terra::ifel(!is.na(streams), 0, friction)
out  <- terra::costDist(cost, target = 0)

costDist(target = 0) finds all cells equal to 0. Stream cells are set to 0 deliberately — but so
is any cell whose friction (percent slope) is already exactly 0. The roxygen says otherwise:

Stream cells are seed points with cost zero. […] streams identifies seed cells (cost = 0).

Demonstration

Synthetic 50x50 grid, friction 10% everywhere, one stream cell, plus a flat (0%) patch 380 m away:

cost at flat-patch centre        : 0      (should be non-zero)
cost one cell beyond the patch   : 50     (should be non-zero)
cost at equal distance, no patch : 1450
cells with cost 0                : 122    (stream cells: 1)

The bundled test DEM hides this — terrain()-derived slope has zero cells exactly equal to 0
(min 1.42e-14), so no existing test can catch it. Production DEMs do produce exact zeros:
integer-metre DEMs, hydro-flattened lake surfaces, and void-filled plateaus all quantize to flat.

Why it matters more now

Under fl_valley_confine() alone, a spurious flat seed lowers cost slightly in ground that was
probably valley anyway. Under per-group attribution (#40) it is worse: a flat patch becomes a free
zero-cost source for whichever group's corridor contains it, so that group's cost mask can spread
across ground its own streams never reach. Cost then stops discriminating between groups exactly
where floodplains are — on flat ground — and membership degenerates toward the distance buffer.

Fix (as landed in 0.4.1, PR #45)

Floor the friction before seeding:

fr   <- terra::ifel(friction == 0, 1e-6, friction)
cost <- terra::ifel(!is.na(streams), 0, fr)

Corrected during implementation: == 0, not the <= 0 originally proposed here.
terra::costDist() rejects a negative cost surface outright (negative friction values not allowed). Flooring <= 0 would have silently disabled that guard, converting input terra
correctly refuses into plausible-looking output — the same failure direction this fix exists to
close. == 0 eliminates exactly the set that costDist(target = 0) would mistake for seeds and
nothing more. A test now asserts the guard still fires.

Also settled by measurement: costDist target matching is exact equality (a 1e-14 cell reads
7.07e-14, not 0), so == 0 is the correct comparison rather than a tolerance.

Note the original "should be ~1400" figures above were wrong in premise — a flat patch legitimately
is cheaper to traverse, so the correct post-fix cost is lower than the no-patch control, not equal
to it. The bug was that flat ground was a source, not that it was cheap to cross.

Blast radius — measured on both shipped DEMs

The fix can only raise a cost that was spuriously zero, so it strictly removes cells from the cost
mask and never adds.

DEM shipped by this package	exact-zero slope cells	cost mask (< 2500)	valley cells
bundled dem.tif / slope.tif, 10 m	0 of 45,726 (min 1.42e-14)	unchanged	53,635 -> 53,635
pars_dem.tif (MRDEM-30, 30 m, 20.9 Mcell)	80 of 10.7 M	-2,289 cells (214 ha), 0 added	521,028 -> 521,028

So MRDEM-30 — the package default source — does produce exact zeros at watershed scale; a small
clip returning none is not evidence about the source. The cost mask moves. The delineation does not,
on either dataset, because the slope, distance and flood criteria plus morphological cleanup absorb
every affected cell — so the shipped vignette artifacts are still current, verified against
pars_valleys.tif directly. That is a property of these two datasets, not a guarantee: where cost
is the binding criterion the delineation will shrink.

Filed separately rather than folded into #40 because it changes VCA output on any DEM that contains
exact zeros — that is a result-changing decision that deserves its own diff and its own regression
check, not a side effect of an attribution feature. Bundled data is unaffected, so no existing test
output moves.

Also fix the roxygen at R/fl_cost_distance.R:9-12 and :19, which currently describes behaviour
the function does not have.

Found during the plan review for #40.

[NewGraphEnvironment]

Exposure check from the driver side: real DEMs on our path do not trigger this

Confirming the bug, and bounding who it affects. We were about to build per-watercourse attribution on this cost surface (NewGraphEnvironment/floodplains#40), so "does it bite us?" needed an answer rather than an assumption — particularly since the watershed groups we most recently published are 61–74% open water, which is exactly where flat ground and therefore exact-zero slope would be expected.

Probed the largest waterbody we have — Kootenay Lake, 423 km² — using the same DEM source the driver always uses (national MRDEM-30 via fl_dem_aoi()), slope derived as terra::terrain():

AOI: 117,174 DEM cells | 62,662 non-NA slope cells
EXACT zeros:   0   (0.000%)
min non-zero:  9.54e-14
cells < 1e-9:  2

Zero exact zeros over a 423 km² lake surface. The reason is the same one that hides it in the bundled test DEM (min 1.42e-14): terra::terrain() derives slope from a 3×3 neighbourhood of floating-point elevations, so even a genuinely flat water surface carries enough float noise to land around 1e-13 rather than exactly 0.

That covers fl_valley_confine(slope = NULL) too, since it derives slope the same way.

So the exposure is narrower than "production DEMs". It is specifically a supplied or ingested friction raster with true zeros — a quantised or integer-typed slope product, a hand-built friction surface, a raster that has been rounded or written at reduced precision. Anything that reaches fl_cost_distance() via terrain() on a float DEM appears safe.

Not arguing against the fix — the roxygen is wrong and costDist(target = 0) genuinely does what this issue says. Just recording that the terrain()-derived path has been checked at scale on flat ground and comes back clean, so it does not need to gate downstream work.

Strong evidence rather than proof across every group, but the mechanism generalises.

Checked under NewGraphEnvironment/floodplains#40.