lnk_wsg_resolve: bundle-aware WSG resolver (closure + species filter); study_area_wsgs.R → CLI shim

[NewGraphEnvironment]

Problem

data-raw/study_area_wsgs.R does three things inline:

1. Read public.wsg_outlet, compute drainage closure (DS-first)
2. Species-filter via the bundle's wsg_species_presence (trifecta + balance + run_provincial: filter dispatch list to bundle species (skip 15 known-empty WSGs) #157)
3. Print a comma list to stdout

It's callable only from bash. Not testable. Not reusable from R sessions, vignettes, or other drivers. The "what WSGs should we model?" decision is captured in a script when it should be a function.

Proposed

lnk_wsg_resolve(cfg, loaded, wsgs = NULL, expand = TRUE)

Param	Role
cfg	lnk_config() manifest
loaded	lnk_load_overrides(cfg) — carries wsg_species_presence for the #157 filter (consistent with the rest of link's API)
wsgs	character vector of seed WSGs; NULL = all bundle-species WSGs (province mode)
expand	when wsgs is non-NULL: TRUE (default) = closure-expand via fresh::frs_wsg_drainage; FALSE = use as-is (species-filter only)

Returns: character vector of WSG codes, DS-first ordered when expanded.

Call patterns

lnk_wsg_resolve(cfg, loaded)                                    # province (all bundle-species WSGs)
lnk_wsg_resolve(cfg, loaded, wsgs = c("PARS","BULK"))           # study-area + drainage closure (default)
lnk_wsg_resolve(cfg, loaded, wsgs = c("BBAR","BULK"),
                expand = FALSE)                                  # exactly these, species-filtered, no closure

Where it lives

R/lnk_wsg_resolve.R. Pre-stages a lnk_wsg_* family if more WSG functions land (e.g. lnk_wsg_list, lnk_wsg_buckets for DS-first chunking across hosts).

What it composes

• fresh::frs_wsg_drainage() (fresh issue — blocker) for the topology closure
• loaded$wsg_species_presence for the trifecta + balance + run_provincial: filter dispatch list to bundle species (skip 15 known-empty WSGs) #157 species filter

Downstream change

data-raw/study_area_wsgs.R shrinks to a thin CLI shim:

• Parse args (focal CSVs, optional --no-expand)
• Build cfg + loaded
• Call lnk_wsg_resolve()
• Print

data-raw/study_area_run.sh interface unchanged externally (still shells to study_area_wsgs.R).

Acceptance

• lnk_wsg_resolve(cfg, loaded, wsgs = c("PARS","BULK")) reproduces the current study_area_wsgs.R output: KISP,KLUM,LKEL,LSKE,MSKE,USKE,BULK,FINA,LBTN,LPCE,MORR,PARA,PCEA,UPCE,PARS (15 WSGs)
• lnk_wsg_resolve(cfg, loaded) returns the full bundle-species province list
• expand = FALSE returns input verbatim (after species-filter)
• Tests for all three call patterns
• Runnable @example
• data-raw/study_area_wsgs.R rewritten as CLI shim; study_area_run.sh adapted, interface unchanged

Blocked on

NewGraphEnvironment/fresh#211 (frs_wsg_drainage)

Replaces

Inline drainage-closure + species-filter logic in NewGraphEnvironment/link@v0.40.5 data-raw/study_area_wsgs.R.

Related

• trifecta + balance + run_provincial: filter dispatch list to bundle species (skip 15 known-empty WSGs) #157 (species-presence filter — the rule this function applies)
• Promote with_mapping_code flag to stand-alone lnk_compare_mapping_code() export #175 (study-area parity — surfaced the need)
• Make id_segment globally unique (position-derived, bcfp-style) — id_segment-alone persist joins cartesian across WSGs #203 (per-WSG id_segment cartesian — adjacent persist correctness)

Naming considered

lnk_wsg_resolve (chosen) — noun-first matches link's dominant pattern (lnk_pipeline_*, lnk_compare_*, lnk_barriers_*, lnk_persist_*). wsgs arg name (not focal) matches existing CLI vocabulary (--wsgs= in wsgs_run_pipeline.sh). loaded param kept for consistency with every other pipeline phase (lnk_pipeline_run, lnk_pipeline_load, etc.) — renaming would be a package-wide sweep, not a one-off.