frs_habitat_overlay: drop format, accept canonical shape only (#177)

[NewGraphEnvironment]

Summary

Closes #177.

Drops format and long_value_col parameters from frs_habitat_overlay(). Accepts only the canonical source-table shape: one row per (segment × species), with join keys + species column + one indicator column per habitat type. Indicator coercion is universal — accepts integer 1, text 'true'/'t'/'1' (case + whitespace insensitive), boolean.

Why drop, not extend

PR #176's first attempt added a species_col parameter to bolt the new bcfishpass shape onto the existing format = "wide" dispatch. On review, that compounded the API rather than fixing the design. The earlier format = c("wide", "long") enum was scoped for two shapes that have no current production consumers:

• format = "wide" per-species-suffixed (spawning_sk, rearing_sk) — was scoped for direct reads of bcfishpass.streams_habitat_known; never integrated
• format = "long" (habitat_type rows + habitat_ind indicator) — was link's pre-2026-04-26 path; bcfishpass moved to a different shape on 2026-04-26

Carrying flexibility for two shapes with zero consumers is YAGNI. Drop them; rebuild when a real second consumer with a different shape appears.

What stays parameterized

param	what it controls
from, to, bridge	which tables
species	which species to process (NULL = all in target)
species_col	name of the column in source carrying the species code (default "species_code")
habitat_types	which habitat columns to overlay
by	join keys (default c("blue_line_key", "downstream_route_measure"))

Bridge mode (3-way range-containment join) is orthogonal to source shape — unchanged.

Non-canonical sources (transform first)

Callers with non-canonical sources (legacy long format, wide-suffix layout) transform first via a SQL view, R pivot, or upstream adapter, then call overlay against the canonical-shape view. The docstring's third example shows the long-to-canonical pivot. Shape-translation lives with the consumer; fresh stays a thin SQL adapter.

Test plan

• devtools::test(filter = "frs_habitat_overlay"): 51 PASS (was 67 with bolt-on)
• devtools::test() full suite: 815 PASS, 0 FAIL (was 831 with the now-removed paths)
• /code-check: Clean. All caller-controlled identifiers validated, NULL-safe coercion, additive guard parenthesised.
• Integration tests cover: integer indicators, text 'true'/'true'/'t' indicators, additive guard (already-TRUE rows untouched), custom species_col, custom by, bridge mode

Coordination

• Fresh ships 0.22.0 with this change (breaking, pre-1.0)
• link picks up fresh 0.22.0 and updates lnk_pipeline_classify call site (separate link PR after this merges; bumps to link 0.12.0 in the same release window)
• crate's registry-driven lnk_ingest_bcfishpass() (canonicalize-at-ingest) lands as a follow-up — not blocking this unblock

Related

• bcfishpass shape change on 2026-04-26 forced the question
• Issue #177 — design doc (force-pushed scope from "layout decomposition" to "drop format")
• crate ↔ link discussion in link/comms/crate/20260427_fresh_bcfishpass_csv_consumers.md
• frs_habitat_overlay: long-format known table support #172 long-format support (closed; introduces the path being dropped)
• frs_habitat_overlay: rename params + add bridge for 3-way joins #174 rename + bridge (closed; bridge orthogonal — stays)

🤖 Generated with Claude Code