Validate modelled habitat against fish observations (#283)

CLAUDE.md

@@ -11,6 +11,30 @@ Experimental package — breaking all the time and loving the learning curve. St
 **Prefix:** `lnk_`
 **Branch:** `main` (v0.49.0 as of 2026-09-01)
 
+## Status (2026-09-26, late) — observation validation (#283)
+
+**`lnk_habitat_validate()` scores a run against fish, not against bcfishpass.**
+Capture on accessible / spawning / rearing, cost in km, miss reasons from the
+bundle's own predicates with gradient and width relaxed, and FISS absences.
+Driver: `data-raw/habitat_validate.R --bundles=<config>:<schema>,...`. Method,
+baseline and the step-5 command: `research/habitat_validation.md`.
+
+**Facts not worth re-deriving:**
+- **fresh#218 is a join artifact, not duplication.** Every persist table is unique
+  on `(id_segment, watershed_group_code)`; a bare `id_segment` join fans out 22x
+  (#203). Join on the full key and the persist schemas are fine.
+- **`default`'s `pipeline.schema` is `fresh`, which the bcfishpass bundle writes.**
+  So `schema` is required, and the function stops if `<schema>.log` records a WSG
+  under another config. `fresh_default` was built by overriding the schema.
+- **CH spawn-staged capture is the overlay.** 237 of 245 locations sit in
+  `user_habitat_classification` spawning reaches that `default` forces. Read
+  `share_*_outside_uhc`.
+- **BT rearing 0.1349 scores in-sample** (it is the P95 of the same locations);
+  hold records out via the `observations` argument.
+- A FISS site that caught fish but listed no species is **not** an absence. That was
+  63 % of BT absences in the first draft. `toupper(NULL)` is `character(0)`, which
+  made an absent `--wsgs` select zero WSGs, and only running the driver found it.
+
 ## Status (2026-09-25) — per-bundle habitat thresholds (#282); #284 parked
 
 **Thresholds now live in the bundle.** Every bundle declares

NAMESPACE

@@ -21,6 +21,7 @@ export(lnk_config)
 export(lnk_config_verify)
 export(lnk_db_conn)
 export(lnk_fanout_judge)
+export(lnk_habitat_validate)
 export(lnk_inputs_verify)
 export(lnk_load)
 export(lnk_load_overrides)

R/lnk_preflight_fresh.R

@@ -98,7 +98,8 @@ lnk_preflight_fresh <- function(required = .lnk_fresh_required(),
 .lnk_fresh_required <- function() {
   c("frs_break_apply", "frs_break_find", "frs_candidates_pick",
     "frs_col_generate", "frs_col_join", "frs_habitat_classify",
-    "frs_habitat_overlay", "frs_network_features", "frs_order_child",
+    "frs_habitat_overlay", "frs_habitat_predicates", "frs_network_features",
+    "frs_order_child",
     "frs_params", "frs_wsg_drainage", "frs_wsg_outlets")
 }
 

data-raw/logs/habitat_validate_283/misses.csv

@@ -0,0 +1,89 @@
+"bundle","stage","species_code","reason","n"
+"default:fresh_default","any","BT","captured",4207
+"default:fresh_default","rear","BT","captured",700
+"default:fresh_default","spawn","BT","captured",38
+"default:fresh_default","any","CH","captured",1577
+"default:fresh_default","rear","CH","captured",434
+"default:fresh_default","spawn","CH","captured",246
+"default:fresh_default","any","BT","fails_gradient",344
+"default:fresh_default","rear","BT","fails_gradient",123
+"default:fresh_default","spawn","BT","fails_gradient",21
+"default:fresh_default","any","CH","fails_gradient",51
+"default:fresh_default","rear","CH","fails_gradient",25
+"default:fresh_default","spawn","CH","fails_gradient",1
+"default:fresh_default","any","BT","fails_gradient_and_width",100
+"default:fresh_default","rear","BT","fails_gradient_and_width",37
+"default:fresh_default","spawn","BT","fails_gradient_and_width",6
+"default:fresh_default","any","CH","fails_gradient_and_width",8
+"default:fresh_default","rear","CH","fails_gradient_and_width",7
+"default:fresh_default","any","BT","fails_width",126
+"default:fresh_default","rear","BT","fails_width",61
+"default:fresh_default","spawn","BT","fails_width",5
+"default:fresh_default","any","CH","fails_width",10
+"default:fresh_default","rear","CH","fails_width",5
+"default:fresh_default","any","BT","not_accessible",42
+"default:fresh_default","rear","BT","not_accessible",13
+"default:fresh_default","spawn","BT","not_accessible",1
+"default:fresh_default","any","CH","not_accessible",27
+"default:fresh_default","rear","CH","not_accessible",10
+"default:fresh_default","spawn","CH","not_accessible",1
+"default:fresh_default","any","BT","post_predicate",89
+"default:fresh_default","rear","BT","post_predicate",47
+"default:fresh_default","any","CH","post_predicate",14
+"default:fresh_default","rear","CH","post_predicate",6
+"default:fresh_default","any","BT","rule_excludes",36
+"default:fresh_default","rear","BT","rule_excludes",11
+"default:fresh_default","spawn","BT","rule_excludes",6
+"default:fresh_default","any","CH","rule_excludes",11
+"default:fresh_default","rear","CH","rule_excludes",2
+"default:fresh_default","spawn","CH","rule_excludes",1
+"default:fresh_default","any","BT","width_null",160
+"default:fresh_default","rear","BT","width_null",61
+"default:fresh_default","spawn","BT","width_null",5
+"default:fresh_default","any","CH","width_null",47
+"default:fresh_default","rear","CH","width_null",23
+"default:fresh_default","spawn","CH","width_null",1
+"bcfishpass:fresh","any","BT","captured",4786
+"bcfishpass:fresh","rear","BT","captured",670
+"bcfishpass:fresh","spawn","BT","captured",41
+"bcfishpass:fresh","any","CH","captured",1722
+"bcfishpass:fresh","rear","CH","captured",519
+"bcfishpass:fresh","spawn","CH","captured",274
+"bcfishpass:fresh","any","BT","fails_gradient",276
+"bcfishpass:fresh","rear","BT","fails_gradient",101
+"bcfishpass:fresh","spawn","BT","fails_gradient",18
+"bcfishpass:fresh","any","CH","fails_gradient",75
+"bcfishpass:fresh","rear","CH","fails_gradient",28
+"bcfishpass:fresh","spawn","CH","fails_gradient",11
+"bcfishpass:fresh","any","BT","fails_gradient_and_width",74
+"bcfishpass:fresh","rear","BT","fails_gradient_and_width",28
+"bcfishpass:fresh","spawn","BT","fails_gradient_and_width",5
+"bcfishpass:fresh","any","CH","fails_gradient_and_width",8
+"bcfishpass:fresh","rear","CH","fails_gradient_and_width",7
+"bcfishpass:fresh","spawn","CH","fails_gradient_and_width",1
+"bcfishpass:fresh","any","BT","fails_width",131
+"bcfishpass:fresh","rear","BT","fails_width",62
+"bcfishpass:fresh","spawn","BT","fails_width",5
+"bcfishpass:fresh","any","CH","fails_width",12
+"bcfishpass:fresh","rear","CH","fails_width",6
+"bcfishpass:fresh","spawn","CH","fails_width",2
+"bcfishpass:fresh","any","BT","not_accessible",181
+"bcfishpass:fresh","rear","BT","not_accessible",89
+"bcfishpass:fresh","spawn","BT","not_accessible",6
+"bcfishpass:fresh","any","CH","not_accessible",48
+"bcfishpass:fresh","rear","CH","not_accessible",15
+"bcfishpass:fresh","spawn","CH","not_accessible",7
+"bcfishpass:fresh","any","BT","post_predicate",71
+"bcfishpass:fresh","rear","BT","post_predicate",38
+"bcfishpass:fresh","any","CH","post_predicate",16
+"bcfishpass:fresh","rear","CH","post_predicate",7
+"bcfishpass:fresh","spawn","BT","rule_excludes",6
+"bcfishpass:fresh","any","CH","rule_excludes",66
+"bcfishpass:fresh","rear","CH","rule_excludes",7
+"bcfishpass:fresh","spawn","CH","rule_excludes",25
+"bcfishpass:fresh","any","BT","width_null",189
+"bcfishpass:fresh","rear","BT","width_null",64
+"bcfishpass:fresh","spawn","BT","width_null",5
+"bcfishpass:fresh","any","CH","width_null",52
+"bcfishpass:fresh","rear","CH","width_null",26
+"bcfishpass:fresh","spawn","CH","width_null",2