Access gating blocks tributaries based on upstream mainstem barriers

[NewGraphEnvironment]

Problem

Access gating incorrectly blocks tributaries based on gradient barriers that are upstream on the mainstem, not downstream of the tributary's confluence.

Evidence from ADMS comparison

Cayenne Creek (wscode 100.190442.999098.995997.058910.326444) enters the mainstem (BLK 356362743) at measure 65,641.

Five gradient_15 barriers exist on the mainstem at measures 190,844 to 200,395 — all far upstream of the confluence. These barriers should NOT block access to Cayenne Creek.

But frs_habitat marks all Cayenne Creek segments as accessible = false for CH (15% threshold species).

bcfishpass correctly considers Cayenne Creek fully accessible for CH, with 272 segments and 62.61 km of rearing habitat.

Impact

This is the primary cause of the remaining CH/CO undercount in the ADMS comparison:

Species	Habitat	fresh	bcfishpass	diff
CH	rearing	94.55	308.23	-69.3%
CO	rearing	123.36	351.19	-64.9%

CH/CO use the 15% access threshold (more gradient barriers exist at lower thresholds). Tributaries that join the mainstem below any 15% barrier are incorrectly blocked.

BT (25% threshold) is less affected but likely also impacted (-13%).

Expected behavior

A gradient barrier on the mainstem should only block access to segments that are upstream of the barrier — i.e., on the same blue_line_key at a higher measure, or on a tributary whose confluence is at a higher measure.

The FWA localcode_ltree at the barrier's position determines which tributaries are upstream. A tributary whose wscode branches off below the barrier's localcode is NOT blocked.

How bcfishpass handles this

bcfishpass.barriers_ch_cm_co_pk_sk contains gradient barriers. load_dnstr() indexes downstream barriers per segment using ltree ancestor queries WITH measure comparisons. A barrier is only "downstream" of a segment if it's on the network path from that segment to the ocean.

Relates to NewGraphEnvironment/link#16

[NewGraphEnvironment]

Investigation (2026-04-10)

Investigated on fresh 0.12.3 with the current ADMS WSG data. The specific bug described (mainstem barriers blocking tributaries via the cross-BLK accessibility check) does not reproduce.

Verification

Tested fwa_upstream() between top mainstem barriers (BLK 356362743, measure >150k) and tributary segments on different BLKs. All return FALSE — the cross-BLK check correctly excludes barriers that aren't on the network path between the segment and the ocean.

upstream_of_barrier = FALSE (all 5 tested tributaries)

Numbers have shifted since issue was filed

Metric	Issue claim (older fresh)	Current fresh 0.12.3	bcfishpass
CH rearing km	94.55	402.99	308.23

Fresh now has MORE CH rearing than bcfishpass (403 vs 308 km). Several fixes since the issue was filed changed the landscape:

• frs_break_find minimum island length filter drops short barriers #118: min_length=0 recovered 39 short barriers (more barriers = tighter access)
• Support configurable gradient break thresholds for channel type classification #101: breaks_gradient auto-derives from spawn/rear maxes (more sub-segments)
• Habitat eligibility rules format for multi-rule species (Path 1) #113: rules YAML expanded rearing to include river polygons + wetland-flow
• SK/KO spawning requires proximity to rearing lake — requires_connected predicate #120: requires_connected for SK/KO spawning

10 fully-blocked tributaries exist but are correctly blocked

The 10 tributaries with >10 segments and 0% accessibility for CH are blocked by legitimate gradient barriers on their own stream (not by mainstem barriers). This is correct behavior.

Remaining CH/bcfishpass gap

The 403 vs 308 km difference (fresh OVER bcfishpass) likely comes from:

1. Rules YAML expanding rearing to include river polygons + wetland-flow carve-out (bcfishpass doesn't have the wetland rule for CH in the same form)
2. bcfishobs observation overrides not yet implemented in fresh (barriers near observed fish could be downgraded in bcfishpass — tracked in Design observation-based break validation without baking in assumptions #69/Apply bcfishpass override CSVs to crossings extract #90)
3. Different gradient break thresholds (fresh auto-derives from spawn/rear maxes; bcfishpass uses fixed 5/7/10/12/15/20/25/30)

Recommendation

Close this issue — the specific cross-BLK bug doesn't exist. The remaining CH/CO gap is explained by rules differences and missing observation overrides, both tracked in other issues.

[NewGraphEnvironment]

Closing — investigated on 0.12.3, the cross-BLK accessibility bug does not reproduce. fwa_upstream() correctly returns FALSE for tributaries vs upstream mainstem barriers. See investigation comment above for full analysis. Remaining CH/CO gap explained by rules differences and missing observation overrides (tracked in #69/#90).

[NewGraphEnvironment]

Still reproduces on fresh 0.12.6

Cayenne Creek (BLK 356333292, wscode 100.190442.999098.995997.058910.326444.537363, stream_order 5, channel_width up to 35m) is marked accessible = false for CH in the ADMS comparison.

bcfishpass v0.5.0 correctly classifies it as CH-accessible with 62+ km of rearing habitat.

Proof

-- Fresh: Cayenne Creek blocked for CH
SELECT s.linear_feature_id, s.blue_line_key, s.gnis_name, s.stream_order,
  s.channel_width, round(s.gradient::numeric, 4) AS gradient, h.accessible
FROM fresh.streams s
JOIN fresh.streams_habitat h ON s.id_segment = h.id_segment
WHERE h.species_code = 'CH' AND s.blue_line_key = 356333292
  AND s.channel_width >= 4
ORDER BY s.channel_width DESC LIMIT 5;
-- All return accessible = false

Root cause

Gradient_15 barriers on the ADMS mainstem (BLK 356362743) at measures 190,844 to 200,395. Cayenne Creek enters the mainstem at measure 65,641 — well DOWNSTREAM of these barriers. The barriers should NOT block Cayenne Creek.

-- Barriers are upstream of confluence
SELECT label, blue_line_key, downstream_route_measure
FROM fresh.streams_breaks
WHERE label = 'gradient_15' AND blue_line_key = 356362743
ORDER BY downstream_route_measure;
-- All at measures 190,844+ (Cayenne confluence is at 65,641)

Impact

207 LFIDs (572 segments) classified as CH spawning in bcfishpass v0.5.0 are blocked in fresh 0.12.6. These account for ~64 km of the 64 km CH spawning gap (213 km fresh vs 278 km bcfishpass).

This is the primary remaining discrepancy in the ADMS comparison (link 0.0.0.9000). BT is within 3% (BT uses 25% access threshold — fewer barriers, less exposure to this bug). CH/CO use 15% threshold with more barriers, amplifying the effect.

Versions

• fresh: 0.12.6
• bcfishpass: v0.5.0
• link: 0.0.0.9000
• fwapg: Docker local (FWA 20240830, cw updated from tunnel)

[NewGraphEnvironment]

Re-investigation (2026-04-11, fresh 0.12.6)

The cross-BLK tributary blocking bug described in the original issue still does not exist. fwa_upstream() correctly returns FALSE for tributaries vs upstream mainstem barriers.

What's actually happening

The CH/CO gap is caused by a different mechanism: bcfishpass filters gradient barriers between the raw gradient_barriers table and the species-specific barriers_ch_cm_co_pk_sk table. Fresh uses all gradient barriers directly.

Proof from Cayenne Creek (BLK 356333292):

-- bcfishpass raw gradient_barriers has a gradient_class=15 at measure 1355:
SELECT downstream_route_measure, gradient_class
FROM bcfishpass.gradient_barriers
WHERE blue_line_key = 356333292
AND downstream_route_measure BETWEEN 1300 AND 1400;
-- → 1355.2, gradient_class=15

-- But barriers_ch_cm_co_pk_sk does NOT include it:
SELECT min(downstream_route_measure)
FROM bcfishpass.barriers_ch_cm_co_pk_sk
WHERE blue_line_key = 356333292;
-- → 40392 (first CH barrier is 40km upstream!)

Fresh blocks Cayenne Creek at 1.3km (the raw gradient_15 barrier). bcfishpass blocks it at 40km. The difference is 39km of accessible habitat on this one creek alone.

Root cause

bcfishpass's model_access SQL scripts apply additional filtering when building species barrier tables from raw gradient barriers. Understanding that filtering is the path to closing the remaining gap — tracked in link.

This is NOT a fresh access gating bug

The access check SQL (same-BLK measure comparison + cross-BLK fwa_upstream ltree) is correct. The issue is about WHICH barriers are included, not HOW they're checked. That's a barrier selection/filtering question for link to solve by replicating bcfishpass's model_access logic.

Closing again. The remaining gap is tracked in link.

[NewGraphEnvironment]

Closing — fresh access gating is correct. The CH/CO gap is caused by bcfishpass filtering gradient barriers before building species access tables, not by a cross-BLK bug. See comment above for proof. Tracked in link.