feat(engine): streams as an answer type + distance-bounded flow tracing

[prayaslashkari]

Recreates UC1-CQ2c from David's notebooks: "What streams are downstream at most N km from facilities of industry X?"

---

1. What this adds

Two capabilities the query builder didn't have:

Streams are now an answer, not just scenery. Flowlines only ever appeared as a decorative layer traced from the anchors — you couldn't ask for them. (waterBodies is hyf:HY_WaterBody: lakes and ponds, which the notebook explicitly swaps out for flowlines.) Streams are now selectable in either block, with a stream-type filter.

Downstream/upstream can be distance-limited. Traces were the full transitive closure — they ran to the ocean and returned half the state. There's now a Within N km of flow dropdown (5/10/30/50/100 km), plus the notebook's "+1" behaviour: the trace extends one segment past the cutoff so a flowpath ends at a river feature rather than mid-channel.

What this opens up for researchers

• Sampling prioritisation. "Which stream segments are within 30 km downstream of an airport or landfill?" — a shortlist you can send a field crew, instead of a statewide guess. Cross it with existing sample coverage to find the gaps.
• Source screening, in reverse. Point at a contaminated stream, flip to upstream, get the facilities plausibly implicated. A hypothesis set narrow enough to investigate.
• Sensitivity testing. The cutoff is a scientific judgement, not a fact. Sweeping 5 → 100 km shows whether a finding is robust or an artifact of the threshold — the sort of check that's tedious in a notebook and trivial here.
• Distance-attributed results. Every stream carries its flow distance from the source, so results can be ranked by proximity rather than treated as a flat set.

One caveat worth repeating in any write-up: this is connectivity, not fate-and-transport. It says water flows from here to there within N km. It says nothing about whether contamination arrives, or at what concentration — no discharge volumes, no dilution, no groundwater. It's a screening layer.

---

2. How it's implemented

'streams' joins EntityType with FTYPE filtering, IRI hydration and map wiring; maxDistanceKm joins SpatialRelationship. When unset, the emitted SPARQL is byte-identical to today's — I diffed generated queries for three existing question shapes to confirm nothing moved.

The distance cutoff. Sum the segment lengths between seed and candidate, then filter on the total. The seed block is duplicated inside the subquery — without it the SUM runs over the entire national flowline graph:

{
  SELECT DISTINCT ?upstream_flowline ?ds_flowline WHERE {
    {
      SELECT ?upstream_flowline ?_flEnd (SUM(?_flLen) AS ?_plen) WHERE {
        {
          SELECT ?upstream_flowline ?_flMid ?_flEnd WHERE {
            { SELECT DISTINCT ?upstream_flowline WHERE { ...anchor seed... } }
            ?upstream_flowline hyf:downstreamFlowPathTC ?_flMid .
            ?_flMid hyf:downstreamFlowPathTC ?_flEnd .
          }
        }
        ?_flMid nhdplusv2:hasFlowPathLength/qudt:quantityValue/qudt:numericValue ?_flLen .
      } GROUP BY ?upstream_flowline ?_flEnd
    }
    FILTER (xsd:float(?_plen) < xsd:float(30))
    ?_flEnd hyf:downstreamFlowPath? ?ds_flowline .   # the "+1"
  }
}

The "+1" is that last line — a zero-or-one path, giving the endpoint and its immediate neighbour in one triple. A UNION says the same thing, but QLever (which the notebooks run against) returns unbound results for MIN() over a UNION-bound variable; I isolated it on a two-row case with no data involved. The path form works on both hosts. Same reason for ?a = ?b over sameTerm() — QLever hasn't implemented sameTerm.

Streams as the target get BIND(?ds_flowline AS ?streamC) instead of the usual ?s2target hop, which would otherwise match any flowline sharing an S2 cell with the answer. The supporting stream layer is skipped in that case, so flowlines aren't drawn twice.

Flow distance for popups uses MIN() per flowline (shortest qualifying path). Fringe segments can't inherit their parent's distance — that would report a sub-threshold number for a flowline outside the threshold — so they carry the parent's path plus the parent's own length.

---

3. How this differs from the notebook

	Notebook	Here	Why
schema1:address on facilities	required	OPTIONAL	Only 13 of 144 NH airport facilities have it. Required, it silently drops 91% of the anchor set.
S2 seeding	facility's own cell	own cell + 8 neighbours	Existing app-wide convention for every spatial relation.
Region binding	facility → county → state	S2 cell → state	How the app already scopes regions; catches 147 facilities vs 144.
Per-stream distance	one value per (seed, endpoint) pair	MIN() across seeds	Each stream needs one number for its popup.

The first row is a bug, and it's the whole story of the count difference — it's why the notebook's map shows about five facilities for a state with 144:

notebook as written                      162 flowlines   (18 seeds, ~13 facilities)
notebook, address requirement removed  1,547            (228 seeds, 144 facilities)
ours, neighbour expansion off          1,605            ⊇ the 1,547, nothing missing
ours as shipped                        2,784

The other three rows are deliberate, and none is new to this PR.

Not carried over: the notebook's navy/blue seed-vs-downstream colour split, its S2-cell overlay, and street address in the facility popup (we have name, industry and an EPA FRS link). All cosmetic.

Also worth knowing: downstreamFlowPathTC in this KG doesn't reach the coast. Unbounded gives 3,490 streams vs 2,784 at 30 km — a narrower closure than the notebook's parameters imply.

---

4. Verification

scripts/flow-distance-check.mjs runs the real planner against the live endpoints and asserts the step plan, the superset relation, that the bound actually excludes flowlines, and that every hydrated stream has drawable geometry. Plain .mjs following scripts/contrast-check.mjs; no test framework added.

Measured (NH, NAICS 488119):

cutoff	streams	fringe added
unbounded	3,490	—
30 km	2,784	+1.0%
10 km	2,096	+3.8%
5 km	1,669	+8.9%

Flowline distances at a 30 km cutoff span 0.01–32.23 km — the over-threshold value is the fringe honestly reporting itself as past the boundary.

The bound also makes previously impossible questions possible: "samples within 30 km downstream of NH airports" returns 27 sample points in ~15 s, where the unbounded form times out against the gateway.

npm run build clean. npm run lint shows the same 15 pre-existing errors as development — none new.

⚠️ FRINK is currently returning 503 on all five endpoints, so the committed check script hasn't been re-run against it since the "+1" commit. The numbers above were verified against apps.okn.us, which I'd earlier confirmed returns byte-identical result sets for these queries. Please re-run node scripts/flow-distance-check.mjs before merging, once FRINK is back.

To try it

Block A = Streams / Flowlines · Relationship = Downstream of + Within 30 km of flow · Block C = Facilities, industry 488119, region New Hampshire.

Put the region on Block C, not Block A. On Block A the anchor becomes every 488119 facility in the country (11,010 across 10,703 S2 cells) and the trace takes minutes — correct, since a Maine stream can be fed from New Hampshire or Quebec, but rarely what you want.

[railway-app]

This PR was not deployed automatically as @prayaslashkari does not have access to the Railway project.

In order to get automatic PR deploys, please add @prayaslashkari to your workspace on Railway.

[prayaslashkari]

Added the "+1" hop from David's second notebook (0ff2f39).

A distance budget runs out at whatever segment happens to fit, which is an artifact of how NHDPlus split the river rather than a real feature — without this the drawn path stops mid-channel. Extending one segment past the boundary means the flowpath visibly crosses the threshold, which is the notebook's stated intent: the total may deliberately exceed the limit.

Always on when a cutoff is set. A checkbox for a 1%-at-30km difference is a control nobody would understand, and "within 30 km" already reads as approximate. Easy to make it a toggle if you disagree.

Effect scales inversely with the cutoff

The fringe is a larger share of a smaller answer set (NH airports, NAICS 488119):

cutoff	without +1	with +1	added
5 km	1,533	1,669	+8.9%
10 km	2,019	2,096	+3.8%
30 km	2,757	2,784	+1.0%

At 30 km it's noise. At 5 km it's a tenth of the result, so it matters most exactly where a researcher is being most selective.

Note this also changes entity answers, not just the drawing — with streams as Block A the fringe is cosmetic, but for "samples downstream of X" it admits sample points sitting on the fringe segment, past the stated distance. That's the notebook's semantics, and it's why the popup number matters (below).

Two implementation notes worth review

Zero-or-one property path, not a UNION. ?end hyf:downstreamFlowPath? ?answer yields the endpoint and its immediate neighbour in one triple. A UNION expresses the same thing, but QLever — which David's notebooks run against — returns unbound results for MIN() over a variable bound inside a UNION. Verified on a two-row test case with no data involved:

SELECT ?k (MIN(?v) AS ?minv) WHERE {
  VALUES (?k ?a ?b) { ("x" 1.0 2.0) ("y" 5.0 3.0) }
  { BIND(?a AS ?v) } UNION { BIND(xsd:float(?a) + xsd:float(?b) AS ?v) }
} GROUP BY ?k

→ QLever returns ?k bound, ?minv missing. The path form works on both hosts. Same reason for ?a = ?b over sameTerm() — QLever hasn't implemented sameTerm.

Fringe distance. Fringe segments can't inherit their parent's path_length, since that reports a sub-threshold number for a flowline outside the threshold. They carry the parent's path plus the parent's own length — the distance to where the fringe segment begins, which never understates. A flowline reachable as both a valid endpoint and a fringe keeps the smaller value, since MIN runs over both.

Verification

FRINK is returning 503 across all five endpoints as I write this, so scripts/flow-distance-check.mjs hasn't been re-run against it. I verified against apps.okn.us instead — the two hosts were confirmed to return byte-identical result sets earlier in this work:

streams @ unbounded: 3490      (unchanged)
streams @ 5km:       1669
streams @ 30km:      2784

flowline distances (5 facilities, 30 km): 113 rows, 113 with path_length
  within cutoff (<30km): 112
  fringe (>=30km):         1
  range: 0.01 - 32.23 km

That 32.23 km fringe value is the check that matters — it's a flowline past the boundary honestly reporting a distance past the boundary.

npm run build clean, npm run lint still the same 15 pre-existing errors. Worth re-running the check script against FRINK before merge, once it's back.