The hint names "broadcast", "balance", "shard" are duplicated as raw strings here and again in SqlToRelCompiler#HintStrategyTable. Two sources of truth for the same registry — easy to drift if one name is renamed or a new strategy added. Consider deriving them from JoinStrategy.Strategy (e.g. Strategy.Broadcast.name().toLowerCase(Locale.ROOT)) and registering them in one place so adding a new strategy is a single-file change.

Also: the default: arm silently drops anything that is not one of the three. Calcite's HintStrategyTable filters unknown names upstream, but a typo on a registered name (e.g. "broadcaast") would silently no-op here. An assertion or a switch keyed on Strategy.values() would catch that.

Two distinct behavioral changes bundled into one condition:

1. !containsHints(node) is wider than it needs to be. The comment two lines down says HYPER_GRAPH_OPTIMIZE "loses hints" — that is specifically about join hints. Any hint anywhere in the tree (a query-level /*+ ... */ on the SELECT, a table hint that has nothing to do with joins) now disables hypergraph reordering for the entire query. Tighten this to "contains a hint on a Join" so unrelated hints do not silently kill an optimization.

2. joinCount(node) > 1 is unrelated to the hint-propagation goal of this PR. Whether or not it is a no-op for single-join queries in practice, the gate change should land with its own rationale and a test that pins the new behavior. Right now nothing in the test suite would notice if this condition were flipped back.

Each of containsCorrelate, containsHints, and joinCount walks the entire RelNode tree independently. On every Hypergraph step invocation that is three full traversals where a single visitor could compute all three predicates at once. Soft — only worth folding together if profiling shows it on a hot path.

Broadcast and Shard are well-known terms in distributed-join literature; Balance is not. A short Javadoc on each variant — what it means operationally, even informally — would save the next reader (or a user reading docs generated from this) a hunt. Especially important since these names are user-facing via /*+ ... */ syntax.

Only broadcast is covered. shard and balance go through the same switch but a typo in one of those case labels would slip past every test in this PR. Parameterizing across JoinStrategy.Strategy.values() is cheap and keeps coverage automatic when new strategies are added.

Also missing: a regression test for the new hypergraph gate — a 3-way join with a join hint, asserting the hint survives end-to-end (i.e. that the gate added in CalciteOptimizer actually does what it says).

hint4(c=id) uses an identifier (id) as the value, but the grammar a few lines below declares optionVal : stringLiteral. Either the example should be hint4(c='id') or the grammar should list simpleIdentifier as an alternative for optionVal.

This section is empty other than "Support for hints is under development." Since the parser now accepts broadcast, shard, and balance without errors (they are registered in HintStrategyTable), users will discover them and try them. A one-line table listing the three names with "recognized but currently no-op" is more honest than the current placeholder and pre-empts the bug report "my hint did nothing."

Typo: "shart" should be "shard". As written, the Shard strategy is registered under the SQL hint name shart, so users have to write /*+ shart */ to get sharded joins, and /*+ shard */ falls through to the default arm in visitJoin and is silently ignored. No test catches this because only broadcast_left is exercised end-to-end.

The gate now combines three conditions, but two of them are conceptually unrelated:

• !containsHints(node) — disabling the hyper-graph rule when any hint is present anywhere in the subtree is much coarser than necessary. A non-join hint elsewhere in the plan (or any future scan/aggregate hint) will silently disable hyper-graph optimization for the whole query. Skipping should be conditional on a hint the rule would actually drop, e.g. a JoinStrategy annotation on a Join.
• joinCount(node) > 1 — this is an independent behavioral change with no rationale comment and no test. If it's meant as a perf guard (don't run hyper on trivial single-join plans), please say so in a comment and add coverage; otherwise it shouldn't be folded into this PR.

Also, three independent recursive walks (containsCorrelate + containsHints + joinCount) over the same tree on every optimizer entry — fine for now, but worth a single visitor if this grows.

Only broadcast_left is exercised end-to-end. broadcast_right, balance, and shard go through the same switch in visitJoin, but each maps to a distinct JoinStrategy.Strategy enum value — easy to typo a case arm (cf. "shart" above). Please parameterize this test or add three more variants asserting the correct annotation per hint.

This PR introduces four user-visible join hints (broadcast_left, broadcast_right, balance, shard) and registers them in HintStrategyTable, but the "Supported hints" section still just says "Support for hints is under development." Either document the four hints here (name, semantics, where they may appear) or add a follow-up issue and link it from this section.

Doc/code mismatch: this lists the hint as balanced(table), but the registered hint name is balance — HINT_BALANCE = "balance" in SqlToRelCompiler, and the new testThreeWayJoinHints writes /*+ ... balance(U) */. A user copying the docs verbatim with /*+ balanced(U) */ will get an unknown hint that silently no-ops. Either rename the constant to balanced or fix the docs to say balance(table).