Refuse unhonoured aggregations; add a real clear-day count to dft_stac_composite (#92)

[NewGraphEnvironment]

Summary

• The bug. aggregation went straight into gdalcubes::cube_view(). That function reads any value it does not know as "none" and raises no error, so dft_stac_composite(aggregation = "count") returned plausible reflectance. The bug has been present since 0.18.0.
• Refusing unhonoured values. dft_stac_fetch(), dft_stac_cube() and dft_stac_composite() now refuse any aggregation outside six values: min, max, mean, median, first and last. Each of the six was measured to survive a cube_view() round trip. The check runs before any network call. Case is ignored, and the value is hashed exactly as given, so no existing cache key moves; a round-3 review computed this against v0.19.2.
• A real count. dft_stac_composite(aggregation = "count") now returns the number of distinct clear days per pixel.
  • It reads one day per time step (dt = "P1D", "first") and counts with reduce_time("count()").
  • It applies no scale, no offset and no offset split.
  • A pixel with no clear day is NA, never 0. gdalcubes returns 0 or NaN for such a pixel depending on chunk layout, and chunk layout follows parallel.
  • Counts are cached under their own family, count_<key>.tif, in INT2U with NEAREST overviews. So the 0.18.0-0.19.2 reflectance-as-count files are never read again.
• Docs. They now say that the default Sentinel-2 mask includes snow, and where to find and delete the orphaned files.

Closes #92. The same silent fallback on resampling is filed as #96.

Measurement

• Live, on a 2 km square, July 2023, cloud_cover_max = 100. 20 items on 12 dates gave counts of 5-9, all whole numbers, no NA. With cloud_cover_max = 20, 6 items on 4 dates gave 4 everywhere, so overlapping MGRS tiles de-duplicate.

• BULK, 20 count chips (300 m buffers, 2023 Jul-Aug), under /usr/bin/time -l:

  run	total	median per chip	peak RSS
  count	577.5 s	24.7 s	0.46 GiB
  same 20 chips as median composites (Dated reference imagery: true-colour composites, NDWI/MNDWI, and RGB layers in dft_map_interactive (+ HLS source) #79)	1,051.6 s	44.4 s	—

  Each count chip's highest count was 5-9. Evidence is in data-raw/logs/benchmark_composite_bulk/*count*. The floodplain-wide read is out of scope while Floodplain-wide tiled composite: terra::mask cannot read the merged mosaic after a 3-hour read #88 is open.

• Chunk invariance. On a 128 x 128 fixture, raw gdalcubes gave 12,544 zeros at 256 px chunks, against 4,352 zeros plus 8,192 NaN at 64 px. After mapping 0 to NA, the two are identical.

Related Issues

• Relates to NewGraphEnvironment/sred-2025-2026#16
• floodplains#93 can now use aggregation = "count" as its issue body describes.

Test plan

• devtools::test(): 1431 pass, 0 fail, 16 network skips
• With DRIFT_TEST_NETWORK=true, the composite file passes all 115 tests, including the new live count test
• devtools::document() and pkgdown::check_pkgdown() are clean
• Every guard added here was mutation-tested: the defect was restored in a scratch copy and the test went red. That covered 20 mutations across aggregation passthrough, the offset split, zero->NA, the key family, datatype, overview resampling, the read step, file prefix, pixel_fn wiring, mask/months/query/resampling/cloud wiring, and case handling in each caller.
• /code-check, 9 rounds over 3 diffs, each round ended by enumeration. The per-round findings are in planning/archive/2026-09-issue-92-aggregation-count/review-*.md.

Notes

• The version is bumped to 0.20.0 because the count is new behaviour.
• The cosmetic "offset split" message that stac_cube_items() prints for a count window straddling 2022-01-25 is left as is.

🤖 Generated with Claude Code

https://claude.ai/code/session_01PRhUJsuKABLfpBGktPoiBN