# catalog/operations/vector/upstream_trace.yaml

id: vector_upstream_trace
name: Upstream Trace
description: >
  Trace upstream from a point or line feature through a flow network,
  collecting all upstream features within distance and count constraints.
  Useful for building drainage basins from stream networks.
version: 1.0.0
category: vector
type: vector-to-vector
default_implementation: native

inputs:
  - name: start_features
    type: vector
    format: geojson
    geometry: Point
    description: Starting point or line features for upstream trace
    required: true

  - name: flow_network
    type: vector
    format: geojson
    geometry: LineString
    description: Flow network with upstream/downstream connectivity
    required: true

  - name: catchments
    type: vector
    format: geoparquet
    geometry: Polygon
    description: Catchment polygons linked to flow network
    required: false

# Structural op — graph traversal over any flow-network vector topology.
requires: {}

outputs:
  - name: traced
    type: vector
    format: geoparquet
    geometry: Polygon
    description: Upstream catchments or dissolved basin polygon

params:
  max_distance_km:
    type: number
    default: 20.0
    min: 0.1
    max: 1000
    description: Maximum upstream distance to trace (in kilometers)

  max_features:
    type: integer
    default: 200
    min: 1
    max: 10000
    description: >
      Maximum number of catchments/features to collect.
      Features exceeding this limit are considered over-extended.

  flow_direction_column:
    type: string
    default: flowdir
    description: Column indicating flow direction in network

  network_id_column:
    type: string
    default: comid
    description: Column linking catchments to network features

  stop_at_orders:
    type: array
    default: []
    description: >
      Stream orders at which to stop tracing (e.g., [4, 5] stops at
      4th+ order streams to avoid tracing into major tributaries)

  dissolve_output:
    type: boolean
    default: true
    description: If true, dissolve all traced catchments into single polygon

cache_policy:
  ttl_days: 30
  invalidate_on: [source_update, param_change]

# backends: audited 2026-08-14 (defect 50). A key means a runtime that DISPATCHES this op —
# folia-engine `dispatch_op` (products/sdk/folia-engine/src/lib.rs), a `registerOp`/OP_TABLE
# entry in packages/compute, `_BUILTIN_OP_MAP` in folia/compute.py, or a backend manifest
# (folia/backends/*/backend.yaml).
backends:
  python:
    function: geo.vector.upstream_trace
    dispatch: folia/compute.py _BUILTIN_OP_MAP

display_hints:
  map:
    renderer: maplibre
    type: fill
    paint:
      fill-color: "rgba(30, 144, 255, 0.3)"
      fill-outline-color: "#1E90FF"

ui:
  icon: git-branch
  color: "#1E90FF"