refactor: migrate query context reference parameters

[FrankChen021]

Description

Follow-up to #20198. Migrates the common query context parameters documented in query-context-reference.md (and scan-query.md) to typed QueryContextParameter descriptors.

• Declares descriptors in QueryContextParameters with types, defaults, range constraints, deprecation metadata and documentation.
• Replaces raw-string reads with descriptor-backed reads, and uses QueryContextBuilder where tests build context maps.
• Adds QueryContextBuilder.putRaw for keys that don't have a descriptor yet.
• Generates the corresponding rows in query-context-reference.md and scan-query.md from the descriptors.

Existing parameter names and defaults are unchanged.

Behavior changes

• Integer and long parameters reject values that aren't exact integers, such as 1.5, and values out of range, instead of truncating or wrapping them. Integral values such as 5.0 or "5.0" are still accepted. Invalid values fail with Query context parameter [x] should be ....
• Writing a null unsets a parameter: withOverriddenContext, withId(null) and the query builders' queryId(null) now remove the key, like the typed setters. Reads already treated an explicit null as unset, so an explicit null maxScatterGatherBytes now gets the server limit.
• A null in the query context, or SET x = NULL, no longer clears a default configured with druid.query.default.context or the Broker dynamic configuration. The default applies, as if the key were not set. Previously the null reached readers, which used the built-in default. To override a configured default, set an explicit value.
• maxSubqueryBytes is a typed string parameter that accepts auto, disabled or a non-negative number of bytes, as the subquery guardrail does. Invalid values such as SET maxSubqueryBytes = TRUE now fail during validation, and numbers such as 1e9 are now accepted.

Deprecations

The key constants replaced by descriptors are deprecated for removal: the migrated QueryContexts.*_KEY constants, BaseQuery.QUERY_ID and TimeseriesQuery.SKIP_EMPTY_BUCKETS. Use the corresponding QueryContextParameters descriptors instead.

---

This PR has:

• been self-reviewed.
• added documentation for new or modified features or behaviors.
• added Javadocs for most classes and all non-trivial methods. Linked related entities via Javadoc links.
• added unit tests or modified existing tests to cover new code paths, ensuring the threshold for code coverage is met.

[FrankChen021]

🟡 Changes recommended

The current head still removes the public TimeseriesQuery.SKIP_EMPTY_BUCKETS constant while retaining the same context key through QueryContextParameters.SKIP_EMPTY_BUCKETS. Downstream extensions or callers compiled against that established field will fail to compile after upgrading; retain a deprecated compatibility alias before merging.

Reviewed 131 of 131 changed files; findings in 1 file. This updated-head review began with the incremental diff from 0ebfbf6a9b250ad35aeab6408bed6eb1b74e0ca2 to the current head, then covered the full merge-base diff and surrounding code.

Validation: git diff --check passed for both the full and incremental committed diffs. No tests or builds were run per the static-review scope.

Severity	Findings
P0	0
P1	0
P2	1
P3	0
Total	1

---

This is an automated review by Codex GPT-5.6-Luna(max)

After addressing the findings or replying to the comments, you can request another review from me to trigger a new automated review.

[FrankChen021]

🟢 Approval recommended

The current head preserves compatibility aliases and correctly handles typed query-context defaults and null semantics. No merge-blocking correctness issues were found.

Reviewed all 165 of 165 files in the current merge-base diff, including surrounding callers, tests, configuration/default precedence, MSQ/server paths, compatibility APIs, and generated documentation. The packet’s file metadata listed 100 entries, so the prepared worktree’s complete current-head diff was used as authoritative.

Validation: git diff --check 308c949996 16d18f372debd94d84d63fec0dbfce1aeb115c13 passed. No builds or tests were run.

---

This is an automated review by Codex GPT-5.6-Luna(max)