invariants: guard hydroseq routing-order completeness (audit finding)

Add .hf_hydroseq_check (flags >0.5% NA or any duplicate hydroseq), wired into
the ngen and merge invariants. Audit finding: hydroseq is 0% NA per-VPU but the
global merge leaves ~1.6% NA (cross-VPU / terminal reaches left unordered) --
the same silent-degradation class as the mainstem_id drop. Tests cover NA /
duplicate / clean. Root-causing the merge's hydroseq recompute is a follow-up;
this guard makes it visible.

Author: Mike Johnson

R/hf_invariants.R

@@ -265,6 +265,7 @@ hf_check_invariants <- function(stage, ..., strict = TRUE,
     checks$ngen_fp_prefix <- .hf_ok(n_bad == 0L,
       sprintf("%d ngen flowpath_id(s) do not start with 'fp-'", n_bad))
     checks$mainstem_id_populated <- .hf_mainstem_check(flowpaths)
+    checks$hydroseq_valid <- .hf_hydroseq_check(flowpaths)
   }
 
   if (!is.null(divides)) {
@@ -344,6 +345,22 @@ hf_check_invariants <- function(stage, ..., strict = TRUE,
       if (frac > 0.05) " -- dropped/mis-mapped?" else ""))
 }
 
+# Shared hydroseq integrity check. hydroseq is the topological routing order:
+# every flowpath needs one (per-VPU outputs are 0% NA) and they must be unique.
+# A NA fraction flags reaches left unordered (e.g. the global merge leaving
+# cross-VPU/terminal reaches without a recomputed hydroseq).
+.hf_hydroseq_check <- function(flowpaths) {
+  if (!"hydroseq" %in% names(flowpaths)) {
+    return(.hf_info("no hydroseq column on flowpaths"))
+  }
+  h <- flowpaths$hydroseq
+  frac_na <- mean(is.na(h))
+  n_dup   <- sum(duplicated(h[!is.na(h)]))
+  .hf_ok(frac_na <= 0.005 && n_dup == 0L,
+    sprintf("hydroseq: %.2f%% NA, %d duplicate(s)%s", 100 * frac_na, n_dup,
+      if (frac_na > 0.005 || n_dup > 0L) " -- routing order incomplete" else ""))
+}
+
 .hf_ring_counts <- function(geoms) {
   vapply(geoms, function(g) {
     if (length(g) == 0L || sf::st_is_empty(g)) return(0L)
@@ -512,6 +529,8 @@ hf_check_merge_invariants <- function(merged, expected = NULL,
 
   # mainstem_id (a global reference levelpath id) must survive the merge intact.
   checks$mainstem_id_populated <- .hf_mainstem_check(fp)
+  # hydroseq routing order must be complete + unique after the global recompute.
+  checks$hydroseq_valid <- .hf_hydroseq_check(fp)
 
   # single CRS across all merged layers
   crs_of <- function(x) if (inherits(x, "sf")) sf::st_crs(x)$epsg else NA

tests/testthat/test-invariants.R

@@ -74,6 +74,23 @@ test_that("ngen stage flags dropped/mis-mapped mainstem_id", {
   expect_true(res2$checks$mainstem_id_populated$ok)
 })
 
+test_that("ngen stage flags incomplete/duplicate hydroseq routing order", {
+  na_fp <- data.frame(flowpath_id = paste0("fp-", 1:10), flowpath_toid = "0",
+    hydroseq = c(1:5, rep(NA, 5)), stringsAsFactors = FALSE)        # 50% NA
+  expect_false(suppressMessages(hf_check_invariants("ngen", flowpaths = na_fp,
+    strict = FALSE))$checks$hydroseq_valid$ok)
+
+  dup_fp <- data.frame(flowpath_id = paste0("fp-", 1:5), flowpath_toid = "0",
+    hydroseq = c(1, 2, 2, 3, 4), stringsAsFactors = FALSE)          # duplicate
+  expect_false(suppressMessages(hf_check_invariants("ngen", flowpaths = dup_fp,
+    strict = FALSE))$checks$hydroseq_valid$ok)
+
+  ok_fp <- data.frame(flowpath_id = paste0("fp-", 1:5), flowpath_toid = "0",
+    hydroseq = 1:5, stringsAsFactors = FALSE)
+  expect_true(suppressMessages(hf_check_invariants("ngen", flowpaths = ok_fp,
+    strict = FALSE))$checks$hydroseq_valid$ok)
+})
+
 test_that("aggregated stage catches duplicate flowpath_id", {
   fp <- data.frame(flowpath_id = c("1", "1"), stringsAsFactors = FALSE)
   expect_error(