# catalog/operations/vector/group_by_name.yaml

id: vector_group_by_name
name: Group Features by Name
description: >
  Group vector features by a normalized name attribute, creating a mapping
  from base names to groups of features. Used to merge HUC12s that share
  a common base name (e.g., "Upper Big Cottonwood" + "Big Cottonwood").
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 — operates on any vector geometry with a name attribute.
requires: {}

outputs:
  - name: grouped
    type: vector
    format: geojson
    description: Features with group_id and group_name attributes added

  - name: group_index
    type: stats
    format: json
    description: Index mapping group_id -> list of feature IDs

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

  normalize_prefixes:
    type: array
    default: ["Headwaters ", "Outlet ", "Upper ", "Lower ", "Middle "]
    description: >
      Prefixes to strip when computing the normalized name for grouping.
      "Upper Big Cottonwood" -> "Big Cottonwood" for grouping.

  min_group_size:
    type: integer
    default: 1
    min: 1
    max: 100
    description: Minimum number of features required to form a group

  id_column:
    type: string
    default: id
    description: Column containing unique feature identifier

  group_id_column:
    type: string
    default: group_id
    description: Output column for the group identifier

  group_name_column:
    type: string
    default: group_name
    description: Output column for the normalized group name

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

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

ui:
  icon: layers
  color: "#9370DB"