Validate codecSpec and support codec-aware forward-index reloads

[xiangfu0]

Context

Stacked on #19307 and part of the split of #18229.

Summary

Completes the activation begun in #19307 by adding semantic table-config validation and reload/rewrite decisions for legacy-to-V7, V7-to-legacy, and V7 spec changes.

Semantic validation and scope enforcement

• Validates the resolved effective ForwardIndexConfig against the closed runtime registry and V7 shape constraints.
• Rejects codecSpec on disabled forward indexes and OPEN_STRUCT children rather than silently discarding it.
• Allows realtime tables to use the normal mutable consuming representation; the codec is applied when an immutable segment is built or committed.
• Keeps a compression-only spec that maps to one legacy ChunkCompressionType on the established raw format.

Reload and rewrite behavior

• Legacy raw → equivalent legacy-compatible codecSpec: no rewrite.
• Legacy raw → V7-requiring transform/chain/non-default option: rewrite to V7.
• V7 → a different canonical V7 spec: rewrite; semantically equivalent canonical specs are no-ops.
• V7 → supported legacy compression (PASS_THROUGH, SNAPPY, ZSTANDARD, LZ4, or GZIP): rewrite to the legacy format for rollback.
• RAW codec rewrites are decided independently of dictionary add/remove and dictionary-optimization outcomes, so combined changes complete in one reload.
• Historical DELTA/DELTADELTA enum values remain only as defensive compatibility if an old invalid config reaches reload; current validation rejects them as user-configurable rollback targets.

Compression statistics

V7 has no single legacy compression enum. Compression statistics now preserve and report the tracked raw uncompressed size with a nullable legacy type, including segment creation and reload, without changing the persisted metadata/API shape.

Verification

• Table-config validation, disabled-forward, immutable/realtime, and OPEN_STRUCT coverage.
• Legacy↔V7, V7 spec change, dictionary add/remove, and heuristic-decline reload tests.
• Actual V7 segment creation/reload tests with compression statistics enabled.
• Spotless, Checkstyle, license format, and license check on all affected modules.

Stack

#19284 → #19285 → #19305 → #19306 → #19307 → #19308 (this PR) → #19309

Review and merge parent-first.

[xiangfu0]

Pushed aafe8c6fd7 correcting the CompressionCodec Javadoc this PR adds. Two issues, both found while assessing whether compressionCodec could be deprecated in favour of codecSpec:

1. The DELTA/DELTADELTA guidance described a migration that is not possible. The previous wording ("For new SV INT/LONG columns, prefer codecSpec=..." / "migrating to codecSpec changes on-disk semantics") implied users have a working compressionCodec: DELTA config to migrate from. They do not: both constants are declared (false, false), so ForwardIndexType.validateForwardIndexEnabled rejects them on the dictionary branch (isApplicableToDictEncodedIndex()) and on the raw branch (isApplicableToRawIndex()) alike. I verified this empirically rather than by inspection — a table config with compressionCodec: DELTA on a RAW single-value INT column, the exact shape the codec targets, fails validation:

IllegalStateException: Compression codec: DELTA is not applicable to raw column: intCol

Same for DELTADELTA and for LONG. Note this makes TableConfigUtils.validateGorillaCompressionCodecIfPresent (the SV / INT-LONG checks for DELTA and DELTADELTA) effectively unreachable on the accept path — the applicability check fires first. That is pre-existing and out of scope here, but worth knowing.

The Javadoc now states plainly that these values are rejected by table-config validation and points to codecSpec="DELTA,LZ4" as the supported route, rather than framing it as a migration.

2. The six constants with no codecSpec equivalent had no Javadoc at all, which read as an oversight next to the four annotated ones. PASS_THROUGH, MV_ENTRY_DICT and the CLP family now each say so explicitly and why:

• PASS_THROUGH — no equivalent; the DSL has no identity codec and rejects a blank spec, and this is the default for METRIC columns, so it stays the only way to state "uncompressed".
• MV_ENTRY_DICT — no equivalent; codecSpec applies only to RAW forward indexes.
• CLP family — no equivalent; whole-index formats for STRING columns rather than chunk codecs, validated against stored type instead of the applicability flags.

I also fixed the malformed {@link CLPForwardIndexCreatorV2) reference in that comment (mismatched brace/paren, and those classes are not reachable from pinot-spi anyway) by using code spans.

Net effect: the guidance now covers all 12 constants and matches what validation actually does. Comment-only change, no behavior difference.

Verification: pinot-spi compiles; IndexCombinationValidationTest, TableConfigUtilsTest, ForwardIndexTypeTest all green (169 tests); spotless/checkstyle/license clean. #19309 has been rebased onto the new head so the chain stays intact.