Data-drive species residence (species_resident/anadromous/spawn_only) from dimensions.csv

[NewGraphEnvironment]

Context

After link#187 (v0.40.0) lands, lnk_pipeline_mapping_code() and lnk_mapping_code() accept species-residence categorization via three params:

• species_resident = c("bt", "wct")
• species_anadromous = c("ch", "cm", "co", "pk", "sk", "st")
• species_spawn_only = c("cm", "pk")

These defaults are hardcoded to bcfp's species residence model. They're flex args (caller can override) but the categorization itself is baked into function bodies, not data-driven from any bundle CSV.

Problem

Operators modelling species outside the bcfp default set — sea-run cutthroat, Dolly Varden, other regional variants — can override at the call site, but the override is invisible to downstream code that re-reads the defaults. Long-term we want species residence to be a property of the bundle's data (which species are modelled + their residence type), not a runtime arg.

Tour-driven motivation: as the user adds custom species mixes per study area, hardcoded defaults become an obstacle. Every override has to land at every call site.

Goals

• Add a residence column (values: resident / anadromous) + spawn_only boolean to parameters_habitat_dimensions.csv (link's bundle CSV in inst/extdata/configs/<name>/dimensions.csv).
• lnk_pipeline_mapping_code() and lnk_mapping_code() derive the three species lists from loaded$parameters_habitat_dimensions when not explicitly passed. Function-arg defaults become last-resort fallback (e.g., for callers that don't have a loaded manifest).
• Each bundle's dimensions.csv documents its species' residence — bcfp bundle keeps the current mapping; default and custom bundles override per study area.
• Cross-repo: investigate whether fresh's parameters_fresh.csv needs a residence column too, or whether the link-side categorization is sufficient.

Acceptance

• parameters_habitat_dimensions.csv (link's bcfp + default bundles) has residence + spawn_only columns populated for current species.
• lnk_pipeline_mapping_code() resolves species_<role> from presence arg OR from loaded$parameters_habitat_dimensions when callable; falls back to current hardcoded defaults when neither is available.
• lnk_mapping_code() passes through the resolved lists.
• A custom-species smoke (e.g., a bundle with only BT + sea-run cutthroat) produces correct mapping_code_<sp> columns without monkey-patching function defaults.
• Fresh-side investigation outcome documented — either fresh#N filed for the corresponding column add, or "no change needed" rationale captured.

References

• R/lnk_pipeline_mapping_code.R — the function whose defaults this issue data-drives.
• R/lnk_mapping_code.R (new in v0.40.0) — pass-through caller.
• inst/extdata/configs/bcfishpass/dimensions.csv and inst/extdata/configs/default/dimensions.csv — schema receivers.
• R/lnk_load_overrides.R / crate ingest — how parameters_habitat_dimensions lands in loaded.
• Follows from mapping_code build decoupled from tunnel — persist streams_access + lnk_pipeline_run phase + rename with_mapping_code → mapping_code #187 (mapping_code tunnel decouple + portable build).