# catalog/operations/vector/name_clean.yaml

id: vector_name_clean
name: Clean Feature Names
description: >
  Clean and normalize feature names by removing prefixes, suffixes, and
  downstream connectors. Extracts the base name from combined names
  (e.g., "Silver Fork Big Cottonwood Canyon" -> "Silver Fork").
version: 1.0.0
category: vector
type: vector-to-vector
default_implementation: native

inputs:
  - name: features
    type: vector
    format: geojson
    description: Input vector features with name attributes
    required: true

# Structural op — string-cleaning over any vector feature with a name attribute.
requires: {}

outputs:
  - name: cleaned
    type: vector
    format: geojson
    description: Features with cleaned name attributes

params:
  name_column:
    type: string
    default: name
    description: Column containing the name to clean

  output_column:
    type: string
    default: display_name
    description: Column to write the cleaned name to

  prefixes_to_strip:
    type: array
    default: ["Headwaters ", "Outlet ", "Upper ", "Lower ", "Middle "]
    description: >
      List of prefixes to remove from names when grouping.
      Include trailing space if the prefix is a word.

  suffixes_to_strip:
    type: array
    default: []
    description: List of suffixes to remove from names

  split_on_connector:
    type: boolean
    default: true
    description: >
      If true, split on '-' and take the first part
      (e.g., "Big Cottonwood Creek-Jordan River" -> "Big Cottonwood Creek")

  name_overrides:
    type: string
    default: "{}"
    description: >
      JSON string of explicit name mappings (raw name -> cleaned name).
      Applied before any other transformations. Format: {"old": "new"}

  canyon_suffix:
    type: boolean
    default: false
    description: >
      If true, replace "Creek" with "Canyon" and add "Canyon" suffix
      where appropriate (for display names of canyon features)

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.name_clean
    dispatch: folia/compute.py _BUILTIN_OP_MAP

display_hints:
  map:
    renderer: maplibre
  table:
    renderer: tanstack-table

ui:
  icon: type
  color: "#4169E1"