Document reserved -1 sentinel contract on PartitionFunction.getPartition

Major fix:
- PartitionFunction.getPartition(String) Javadoc now explicitly states
  the return-value contract: implementations must return non-negative
  partition ids in [0, getNumPartitions()), and -1 is reserved as a
  framework-internal sentinel for "expression evaluated to null"
  (PartitionPipelineFunction.NULL_RESULT_PARTITION_ID). Custom plugin
  partition functions must not return -1 as a real partition id;
  internal callers (broker pruner, stats collector, segment processing
  partitioner) treat -1 as "skip / no partition".

Skipped findings (with rationale):
- Broker pruner fail-open metric: requires introducing a new
  BrokerMeter; defer to a follow-up that adds the meter alongside
  similar pruning failure observability.
- End-to-end integration test: substantial test infrastructure work
  (CustomDataQueryClusterIntegrationTest subclass with controller +
  realtime ingestion + broker routing assertions); defer.
- PR-scope split: process feedback that requires coordinated landing
  with maintainers; out of scope for code-only fixes.
- Cross-version controller-side gate: substantial Helix integration;
  documented hazard in ColumnPartitionConfig Javadoc, defer.
- ColumnBoundPartitionFunction.evaluate null handling: reviewer's
  claim that legacy partition functions produced a deterministic
  partition id for null is incorrect — legacy
  PartitionFunction.getPartition(String) would NPE on
  value.getBytes(UTF_8). The wrapper's null→null conversion is a
  graceful improvement.

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

@@ -47,8 +47,15 @@ public interface PartitionFunction extends Serializable {
    * Method to compute and return partition id for the given value.
    * NOTE: The value is expected to be a string representation of the actual value.
    *
+   * <p><b>Return-value contract:</b> implementations must return a non-negative partition id in
+   * {@code [0, getNumPartitions())}. The value {@code -1} is reserved as a framework-internal sentinel for
+   * "expression evaluated to null" (see
+   * {@link org.apache.pinot.segment.spi.partition.pipeline.PartitionPipelineFunction#NULL_RESULT_PARTITION_ID}) —
+   * custom plugin implementations must not return {@code -1} as a real partition id. Internal callers
+   * (broker pruner, stats collector, segment processing partitioner) treat {@code -1} as "skip / no partition".
+   *
    * @param value Value for which to determine the partition id.
-   * @return partition id for the value.
+   * @return partition id for the value (non-negative for real partitions; never {@code -1}).
    */
   int getPartition(String value);