Calc Commons Guidelines

These instructions apply to iotdb-core/calc-commons/ and supplement the repository instructions.

Responsibilities and code placement

This module provides reusable query computation and execution for server and stream execution environments. Place reusable operators, column transformations, aggregation, joins, sorting, windows, and their execution/memory utilities here, under org.apache.iotdb.calc.
Shared node models and infrastructure belong in node-commons. Keep concrete storage/DataRegion integration, fragment lifecycle, and node scheduler wiring in the owning node module; separate reusable computation from that integration.
Existing SQL constants are also consumed by ConfigNode and CLI. Such usage does not make this module a destination for arbitrary shared utilities. Choose by responsibility and actual dependencies; do not relocate existing code solely because of its package or class name.

The dependency direction is calc-commons -> node-commons, never the reverse. Do not introduce Maven dependencies or Java imports on concrete DataNode/ConfigNode implementations.
Obtain host services through common contexts or small provider interfaces. For example, CommonOperatorContext supplies the execution context, while file-service providers abstract temporary/object-file access. Keep their node-specific implementations in the consuming module. Do not downcast to DataNode's OperatorContext or access a concrete node singleton from shared computation code.
When changing a shared interface, inspect its implementations and callers across consuming modules. Preserve use from standalone/test contexts without requiring a running DataNode.