id: temporal_rolling
name: Rolling
description: >
  Rolling window aggregation over a time series. Computes an aggregate
  over a trailing time window for each row using DuckDB window functions.
version: 1.0.0
category: transform
type: table-to-table
default_implementation: duckdb

inputs:
  - name: table
    type: table
    format: parquet
    description: Input table with a timestamp column
    required: true

requires: {}

outputs:
  - name: result
    type: table
    format: parquet
    description: Table with original columns plus rolling aggregate columns

params:
  time_column:
    type: string
    description: Name of the timestamp column
    required: true
  window:
    type: string
    description: >
      Window size as a duration shorthand (e.g., '3D' for 3 days,
      '7D' for 7 days, '24h' for 24 hours).
    required: true
  value_columns:
    type: array
    items:
      type: string
    description: Columns to compute the rolling aggregate on
    required: true
  agg:
    type: string
    default: mean
    enum: [mean, sum, min, max, count]
    description: Aggregation function for the rolling window

# 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: temporal.ops.rolling
    dispatch: folia/compute.py _BUILTIN_OP_MAP

display_hints:
  chart:
    renderer: observable-plot
    chartType: area
    xAxis: { field: ts }