Global-merge (Stage 4) conservation + completeness invariants — hf_check_merge

Complements the structural merge checks (id-uniqueness, prefixes, toid resolution, divide FK, DAG) with the conservation/completeness class that catches SILENT data loss or corruption when per-VPU fabrics are merged into a global domain: a dropped/duplicated feature, lost catchment area, a missing VPU, zeroed drainage area (the `add_measures` zero-fill class), mixed CRS, or an untagged feature. Reusable across any domain merge.

Usage

hf_check_merge_invariants(
  merged,
  expected = NULL,
  area_tol = 0.005,
  stage = "merge",
  strict = FALSE,
  gpkg = NULL
)

Arguments

merged: named list with `flowpaths`, `divides`, `nexus` (sf/data.frame) for the merged domain product.
expected: optional list of input expectations summed over the per-VPU inputs: `vpus` (character), `n_flowpaths`, `n_divides`, `area_sqkm`. When a field is absent the corresponding check reports as info (skipped).
area_tol: fractional tolerance for divide-area conservation (default 0.005).
stage: message label (default "merge").
strict: if TRUE, a failed check stops execution (else warns).
gpkg: optional path to the written product. When supplied, the CRS check reads every spatial layer from the file rather than only the tables passed in `merged`; a product holds layers this function never sees, and a check that inspects a subset while reporting on the whole is worse than none.

Value

invisibly `list(ok, stage, checks)`.

Examples

if (FALSE) { # \dontrun{
merged <- list(
  flowpaths = sf::read_sf("conus.gpkg", "flowpaths"),
  divides   = sf::read_sf("conus.gpkg", "divides"),
  nexus     = sf::read_sf("conus.gpkg", "nexus")
)
hf_check_merge_invariants(merged,
  expected = list(vpus = sprintf("%02d", 1:18)))
} # }