Document identity-only contract of getPartitionIdNormalizer

Minor clarification: the reviewer flagged that legacy partition
functions (HashCodePartitionFunction / ByteArrayPartitionFunction)
use Kafka-style abs handling Integer.MIN_VALUE → 0, while
PartitionIntNormalizer.ABS does strict mod-then-abs. These differ at
the MIN_VALUE edge case. The string returned from
getPartitionIdNormalizer is purely advertised for staleness/identity
matching between config-side and segment-side function metadata, not
used to drive runtime normalization for legacy functions (which have
their own internal partition-id calculation). Expression-mode
pipelines are the only code path where this value is authoritative
(via PartitionIntNormalizer.fromConfigString).

Document the contract on the SPI Javadoc so plugin authors and
future maintainers don't mistake the string for a runtime hook.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: xiangfu0

pinot-segment-spi/src/main/java/org/apache/pinot/segment/spi/partition/PartitionFunction.java

@@ -103,6 +103,15 @@ default String getFunctionExpr() {
     return null;
   }
 
+  /**
+   * Reports the int-normalizer used by this partition function (e.g. {@code POSITIVE_MODULO}, {@code ABS},
+   * {@code MASK}). The returned string is used by the framework only for identity / staleness matching between
+   * config-side and segment-side function metadata; it does not drive runtime normalization. Legacy partition
+   * functions (Murmur, FNV, HashCode, ByteArray, Modulo) report the closest matching normalizer name even though
+   * their internal implementation may differ subtly at edge cases (e.g. Kafka-style abs handling
+   * {@code Integer.MIN_VALUE → 0} vs strict mod-then-abs). Expression-mode pipelines drive normalization through
+   * {@code PartitionIntNormalizer} directly and are the only code path where this value is authoritative.
+   */
   @JsonIgnore
   @Nullable
   default String getPartitionIdNormalizer() {