id: temporal_align
name: Align
description: >
  Align two time series to common timestamps using ASOF JOIN. For each
  row in the left (primary) table, finds the nearest prior or equal
  timestamp in the right (secondary) table.
version: 1.0.0
category: transform
type: table-to-table
default_implementation: duckdb

inputs:
  - name: left
    type: table
    format: parquet
    description: Primary time series (timestamps are preserved)
    required: true
  - name: right
    type: table
    format: parquet
    description: Secondary time series (values matched to left timestamps)
    required: true

requires: {}

outputs:
  - name: result
    type: table
    format: parquet
    description: Combined table with aligned time series

params:
  time_column:
    type: string
    description: Name of the timestamp column (must exist in both tables)
    required: true
  method:
    type: string
    default: nearest
    enum: [nearest]
    description: >
      Alignment method. 'nearest' uses ASOF JOIN to match the closest
      prior or equal timestamp.

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

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