Add codec spec DSL and configuration plumbing

[xiangfu0]

Context

This is the bottom layer extracted from #18229 after the request to split the codec-pipeline work and land the DSL plus configuration wiring first.

Native GitHub stack:

• This PR: DSL and config contract
• Add bounded codec runtime and compression handlers #19285: bounded internal runtime and compression handlers

What changed

• Replaces the unreleased outer CODEC(...) form with an ordered invocation list such as DELTA,ZSTD(3).
• Adds immutable, bounded structural parsing and canonicalization for codec invocations.
• Adds nullable indexes.forward.codecSpec support to ForwardIndexConfig, including JSON, builder, copy, equality, RAW-only validation, and mutual exclusion with legacy compressionCodec.
• Reconciles legacy noDictionary and top-level compression signals with the nested forward-index config.
• Fails closed anywhere config validation can be bypassed: table validation, immutable creator selection, realtime mutable indexes, preprocessing, and config-aware reader creation.
• Rejects codec specs for OPEN_STRUCT materialized children during table validation and again before the splitter replaces a child forward config.

Safety and compatibility

This layer does not activate codecSpec and does not change any on-disk format. Every non-null spec is deliberately rejected before a reader, writer, or mutable index can silently ignore it. Activation will be a later stacked PR after the runtime and reader/writer lifecycle are reviewable.

The unreleased CODEC(...) syntax is intentionally not retained as an alias.

Tests

• 31 codec AST/parser and ForwardIndexConfig tests
• 171 targeted forward-index/config validation tests
• 33 focused OPEN_STRUCT validation and splitter tests
• focused post-review parser and reader-gate regressions
• Spotless, Checkstyle, license format, and license check for pinot-segment-spi and pinot-segment-local

[Copilot]

Pull request overview

Adds the codec-spec DSL and configuration plumbing while keeping codec execution disabled.

Changes:

• Adds bounded parsing and immutable codec AST types.
• Adds codecSpec to forward-index configuration.
• Adds fail-closed validation across creation, loading, preprocessing, and realtime paths.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
ForwardIndexConfig.java	Adds codec-spec configuration support.
CodecSpecParser.java	Parses and canonicalizes the DSL.
CodecPipeline.java	Represents ordered codec stages.
CodecInvocation.java	Represents individual codec calls.
ForwardIndexType.java	Reconciles configuration and rejects activation.
ForwardIndexReaderFactory.java	Adds reader-side rejection.
ForwardIndexCreatorFactory.java	Adds creator-side rejection.
ForwardIndexHandler.java	Rejects preprocessing with codec specs.
ForwardIndexConfigTest.java	Tests configuration behavior.
CodecSpecParserTest.java	Tests parsing and limits.
CodecPipelineTest.java	Tests pipeline immutability.
CodecInvocationTest.java	Tests invocation validation.
TableConfigUtilsTest.java	Tests table validation.
ForwardIndexHandlerTest.java	Tests preprocessing rejection.
ForwardIndexTypeTest.java	Tests reconciliation and mutable indexes.
ForwardIndexReaderFactoryTest.java	Tests reader rejection.
ForwardIndexCreatorFactoryTest.java	Tests creator rejection.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 76.84729% with 47 lines in your changes missing coverage. Please review.
✅ Project coverage is 67.11%. Comparing base (b6cd43b) to head (ad52533).

Files with missing lines	Patch %	Lines
...pache/pinot/segment/spi/codec/CodecInvocation.java	60.97%	10 Missing and 6 partials ⚠️
...pache/pinot/segment/spi/codec/CodecSpecParser.java	86.02%	5 Missing and 8 partials ⚠️
.../apache/pinot/segment/spi/codec/CodecPipeline.java	42.10%	10 Missing and 1 partial ⚠️
...he/pinot/segment/spi/index/ForwardIndexConfig.java	82.60%	2 Missing and 2 partials ⚠️
.../local/segment/index/forward/ForwardIndexType.java	80.00%	0 Missing and 2 partials ⚠️
.../segment/index/openstruct/OpenStructIndexType.java	66.66%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##             master   #19284      +/-   ##
============================================
+ Coverage     67.09%   67.11%   +0.02%     
  Complexity     1424     1424              
============================================
  Files          3459     3462       +3     
  Lines        219789   219986     +197     
  Branches      35007    35059      +52     
============================================
+ Hits         147457   147654     +197     
+ Misses        60543    60526      -17     
- Partials      11789    11806      +17     

Flag	Coverage Δ
integration	100.00% <ø> (ø)
integration1	100.00% <ø> (ø)
integration2	0.00% <ø> (ø)
java-25	67.11% <76.84%> (+0.02%)	⬆️
lane-a	100.00% <ø> (ø)
lane-b	0.00% <ø> (ø)
temurin	67.11% <76.84%> (+0.02%)	⬆️
unittests	67.11% <76.84%> (+0.02%)	⬆️
unittests1	57.76% <73.39%> (+0.03%)	⬆️
unittests2	39.18% <11.82%> (-0.01%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.