Build logical links from raw stream line segments — build_logical_stream

Joins exact-endpoint, degree-two continuations using sfnetworks. This is topological concatenation, not cartographic smoothing or a length threshold. Coordinate order is not interpreted as flow direction. Junctions, terminals, attribute boundaries, and explicitly protected endpoints remain boundaries. All edges in undirected cycles, self-intersections, overlaps, duplicates, interior crossings, and endpoint near misses are retained without merging. This conservative operation does not snap, split, repair defects, or establish hydrologic direction. Missing boundary values may join other missing values, but never known values. Undeclared semantic boundaries cannot be inferred.

build_logical_stream_links(
  lines,
  boundary_fields = character(),
  protected_nodes = NULL,
  tolerance = 0
)

Arguments

lines: Nonempty projected XY LINESTRING sf object. Normalize multipart features before calling this function.
boundary_fields: Character names of atomic attribute columns whose values must agree for a join. Only these attributes are retained on links.
protected_nodes: Optional sf or sfc POINTs in the same CRS, each exactly coincident with an existing endpoint. No nearest-node matching is performed.
tolerance: Nonnegative endpoint near-miss distance in CRS units. It protects implicated edges from merging; it is never a snapping distance.

Value

A list with `links` (sf, one row per logical link, `link_row` plus boundary attributes) and `membership` (tibble with `link_row`, `input_row`). Every input row occurs exactly once in membership. Row keys are local to this result, not persistent identities. Singleton coordinate order and input objects are unchanged; merged coordinate order is arbitrary.