feat(query): add opt-in distributed broadcast join planner

[discord9]

I hereby agree to the terms of the GreptimeDB CLA.

Refer to a related PR or issue link (optional)

Stacked on #9206; merge #9206 first. This branch includes its review follow-up and read-preference wire correction by ordinary merge.

What's changed and what's your intention?

Add an opt-in, default-off experimental_dist_join path for supported two-scan INNER equijoins. Broadcast the smaller input to the larger table's datanodes rather than joining both remote scans on the frontend.

• Put SMALL on DataFusion's left/hash-build side and BIG on the local right/probe side; restore SQL column order with an existing Projection. BIG-region routing/pruning and producer identity remain intact. DataFusion's JoinSelection remains in control; there is no forced global input order.
• Supply ordinary MergeScan row estimates from selected unique regions' leader heartbeat observations, using checked arithmetic. Rows are Inexact; memory and column statistics remain unknown. The disk-size placement heuristic is not a hash-memory estimate. Unknown/unusable statistics leave planning unchanged.
• Retain complete-result, schema and execution-role tests through the actual SQL setting. No shuffle/general distributed join, self-join or aggregate-side support is added. No new service, protobuf schema or persisted format is introduced. The prerequisite carries typed read preference through supporting receivers using an existing context-extension map.

Limits: Query admission is unchanged. Positive max_concurrent_queries can cause nested requests to time out while outer streams hold permits; default-disabled tests do not establish finite-quota success. Typed read preference is preserved across updated receivers; old receivers still ignore its internal carrier. This change does not add enterprise bootstrap or follower lifecycle support. Earlier release/ECS measurements used an older BIG-build implementation and are not performance evidence for this SMALL-build stack.

Verification: Local checks passed on clean head 2c016aa0ca4fca6ab862b84aabcb0402d0a04863:

• cargo check --locked -p query -p operator -p session -p meta-client -p datanode -p flow -p servers -p tests-integration --tests — passed.
• cargo nextest run --locked -p query -p operator -p session -p common-session -p meta-client --lib --retries 0 -j 4 --no-fail-fast — 1,098 passed, 2 existing skips.
• Focused datanode tests (factory installation and unchanged parallelism) — 2 passed. cargo nextest run --locked -p tests-integration --lib --retries 0 -j 1 --no-fail-fast -E 'test(nested_merge_scan_capability_test) | test(test_flow_requester_health_check_and_handle_request)' — 6 passed, including actual SQL planning/execution and both datanode/Flow strict-ingress regressions.
• cargo nextest run --locked -p servers --lib --retries 0 -j 2 -E 'test(grpc::greptime_handler::tests) | test(http::hints::tests) | test(http::read_preference::tests)' — 7 passed.
• cargo clippy --locked -p query -p operator -p session -p meta-client -p datanode -p flow -p servers -p substrait@1.4.0-alpha.0 -p tests-integration --all-targets -- -D warnings — passed. Formatting, TOML, license-header, spelling and Snafu checks passed.
• Rebuilt greptime and sqlness-runner; greptime --version reports the exact commit above and clean: true. sqlness-runner bare -t '^(standalone|distributed):(create|view|dist_join)$' -c tests/cases --bins-dir "$CARGO_TARGET_DIR/debug" — all 7 distinct standalone/distributed cases passed. Generated SQL expectations are unchanged.

The actual SQL integration retains all 4,877 projected rows against the frontend and known-row references, original SELECT * schema/results, SMALL hash-build/BIG probe roles on each dispatched datanode, and BIG-region pruning. The SQLness case checks off→on→off plans and the complete ordered six-column result. Current-head CI and performance are not yet claimed; Draft-skipped jobs will not be counted as functional test passes.

Additional local enterprise validation: The current #9206/#9404 OSS stack was tested against current enterprise sources with a local companion factory registration. The enterprise-enabled nested/wire/Region/Flow suite passed all 10 selected tests without retries, including normal pre-build-hook construction, real outer/inner TCP Flight follower reads with complete known/frontend result parity, failure without an available follower and no nested leader fallback, and the four supported typed-preference protobuf roundtrips. Strict all-target lint, focused caller/native-datanode regressions, formatting, and a fresh enterprise binary build passed. A separate real enterprise CLI metasrv/datanode/frontend run passed ordinary SQL with the exact complete three-row schema/results; startup identity and owned-process cleanup were checked. The private companion is local only, not part of these OSS PRs or an enterprise release. The focused fixture opens physical followers explicitly; neither it nor the ordinary-SQL CLI check proves automatic follower lifecycle or a single CLI follower end-to-end scenario.

PR Checklist

• I have written the necessary rustdoc comments.
• I have added the necessary unit tests and integration tests.
• This PR requires documentation updates.
• API changes are backward compatible.
• Schema or data changes are backward compatible.
• This PR needs to be backported to release branches, and I have added the backport-<target> labels (e.g. backport-v1.3 targets release/v1.3).