R/connect_stream_network.R
connect_stream_network.RdUses exact shared endpoints to construct a downstream-oriented sfnetwork copy, then hydroloom to derive and order all downstream connections. Storage geometry remains downstream to upstream and is never changed. Diversions retain every connection; no main path or segment role is inferred.
connect_stream_network(stream_network)Nonempty projected XY LINESTRING sf with unique UUID `stream_network_segment_id`, one `stream_network_observation_id`, and `direction_status`. Coordinate order must be downstream to upstream. Optional `upstream_node_id`/`downstream_node_id` UUIDs are reused when consistent with exact endpoint sharing; missing identities are generated. Different IDs at one endpoint, or one ID at different endpoints, are errors.
A list with `stream_network` (input attributes/geometry with node FKs), `stream_network_node` (POINT sf with node/observation UUIDs, `in_degree`, `out_degree`, `node_topology`), and `stream_network_connection` (tibble). Connections contain observation UUID, upstream `stream_network_segment_id`, nullable `downstream_segment_id`, and `node_id` at their shared endpoint. Each observed outlet has one row with a missing downstream segment. Rows follow hydroloom's upstream-to-downstream ordering, with repeated segment IDs at diversions. Node IDs are observation-scoped candidate identities, not cross-observation matches. Preserve returned node FKs for repeat calls.
All directions must already be CONFIRMED. Closed/self-intersecting lines, duplicates, overlaps, interior intersections, and directed cycles block this operation. Near endpoints remain separate; there is no snapping or tolerance. Disconnected components and multiple outlets are permitted and remain subject to observation review. A boundary is only the edge of the observed network, not evidence of a physical headwater or mouth. This is not acceptance validation.