Downstream-state guard: fail loud when downstream dams aren't persisted

[NewGraphEnvironment]

Summary

Enforces the DS-first precondition data-raw/wsg_run_one.R has stated in its own header since #175 and that nothing checked. Accessibility is not computed from the focal watershed group alone — link reads the already-persisted barriers of the groups downstream — so modelling out of order writes streams_access / streams_mapping_code marking segments accessible that are in fact dammed off, prints done in N min, and exits 0. A wrong answer indistinguishable from a right one.

New exported lnk_wsg_downstream_check() verifies it: find the blocking dams on the focal WSG's downstream flow path, confirm each is already persisted as a barrier, fail loud naming them when not.

The finding that reshaped the design

The issue proposed checking for blocking dams in the downstream closure's WSGs — a membership test. Measured live, it cries wolf on the issue's own motivating example:

focal	membership	path	reality
BULK	fires — 18 dams across LSKE/KISP/KLUM	0	none below BULK's outlet
PARS	fires	3	Peace Canyon, Site C, W.A.C. Bennett — correct
SLOC	fires	1	Brilliant Dam — correct

At that rate operators reach for the override reflexively and the guard stops meaning anything — the failure the issue's own "make or break" caveat warns about, though it attributes the cause to edit-CSV fidelity rather than the predicate.

The path form tests each dam with the measure-aware whse_basemapping.fwa_downstream() from fresh::frs_wsg_outlets(). It is complete, not merely cheaper: access walks downstream from every segment and every focal segment exits through the focal outlet, so the out-of-WSG barriers reachable from any focal segment are exactly those below it. ~0.5 s against a 5 s budget. RUNBOOK.md §8c carries the measurement so it isn't "simplified" back.

Three further corrections to the issue body

• Not fwa_watershed_groups_poly for the proposed 2.4 s spatial join — code columns are NULL on docker fwapg (test-lnk_wsg_resolve live tests route to wrong DB (skip-gate vs lnk_db_conn mismatch) #222). watershed_group_code comes from the snapped fwa_stream_networks_sp row, as prep_dams itself does; also 8× faster.
• .lnk_wsg_persisted() is the wrong granularity — cannot distinguish a WSG persisted with dams = FALSE, which would pass a schema holding streams but not barriers. Persistence checked per dam.
• "study_area_run.sh runs pass unchanged" is unachievable by a hard pre-flight — downstream groups are legitimately mid-flight on another cypher, and per-WSG failures soft-fail, so the WSG would be skipped, which lnk_access(merge=TRUE) cannot repair. Strictly worse than the bug. Resolved with warn on both legs + a post-condition in wsg_recompute_one.R.

Anti-drift by construction, not by comment

The cabd and matched CTE bodies now live once and are consumed by both .lnk_pipeline_prep_dams() and the probe, parameterized on source — staged tables for the pipeline, inline (VALUES …) for the guard. A guard that snapped or filtered differently would flag dams the pipeline treats as passable.

A golden capture was taken before the refactor and diffed after: byte-identical for ADMS (8 dams), KOTL (41), PARS (0).

Also fixes a v0.45.0 defect

.lnk_log_create_tables() built the run-log tables but never the schema, so a brand-new persist schema failed with schema does not exist. The log opens before lnk_persist_init by design (the open row must predate any write so wsg_upstream reflects the starting state), and every schema tested until now already existed. Found by running the guard's smoke tests into scratch schemas.

Verified live, end to end

case	result
typo'd LNK_GUARD_DOWNSTREAM	errors — a typo must not silently disable the guard
PARS, empty persist schema	exit 1, names all three dams + DS-first order
ADMS, brand-new schema	passes, models in 2.1 min, log row lands
override	proceeds; note: guard(override): 3 unmodelled downstream dam(s) — PCEA(1), UPCE(2) — Site C fishway operational, ref doc-123
warn	proceeds; note: guard(warn): … at open

Suite 1513 pass, 0 failures. No new lint classes.

Reviewer notes

• The override requires a written justification; a bare TRUE is rejected — the justification is the mechanism, and it lands in <persist>.log.notes beside wsg_upstream so lnk_log_read() reports afterwards that a network was built on a stated assumption.
• study_area_run.sh exports warn on both legs — local subshell and inside the ssh string. Missing the second is the silent failure mode.
• Known bound, recorded in §8c: inherits frs_wsg_drainage()'s one-outlet-per-group model.
• Follow-up cabd_additions dams carry barrier_ind = t but can never become barriers (psc NULL) #244 filed rather than fixed: cabd_additions dams carry barrier_ind = t but can never become barriers (psc NULL). Two of three remedies change modelled access in the Columbia and need a parity check; pinned by a test either way.

Closes #227

🤖 Generated with Claude Code

https://claude.ai/code/session_014kSEJoad4Bc553qU8eFiE6