test(gfql): lock range-chain index decline

[lmeyerov]

Summary

• Add structured IndexDecisionCode values to the GFQL index planner trace and gfql_explain().
• Keep decision_reason as human-readable context while tests assert stable codes.
• Lock scan/index result parity for range-chain and other declined index shapes.

Behavior

Indexes affect optimization choice and explainability, not query results. index_policy="force" bypasses only the cost gate for an index-coverable shape. If the shape is unsupported or an index is unavailable, GFQL scans and returns the same result.

The diagnostics distinguish policy-off scans, no resident index, unsupported shapes, missing graph columns, automatic cost declines, selected indexes, engine mismatches, and unavailable index paths.

Validation

• ./bin/lint.sh
• MYPY_CMD="uvx mypy==2.3.0" ./bin/mypy.sh
• DGX official all-GPU focused range-chain test
• DGX official all-GPU index suite
• Full PR CI was green before this documentation-only changelog commit.

[lmeyerov]

Two smells:

• Error checking should be possible via a structured symbol, eg, known code in a structured field, or a named exception type. Potentially a category level of fix here to do / start (and enforce in skill files)

• Requiring an index to do a query is odd. It makes sense to make missed index-enableable optimizations detectable in a verbose mode or special strictness mode, but generally, this seems unnecessary. At the same time, there may be some special types we 'assume' and are not user-controllable. There is probably some normal database implementation notions here we can follow. Currently, however, the interplay of publicly controllable index interfaces vs query interpretation is weird -- normally indexes should impact performance, not results. Users do appreciate performance tools, but they should not be on the typical paths, but explicit opt-ins, and by default, "want things to work". There may be a deeper fix here too.

[lmeyerov]

• It was addressed in #1840, not ignored.

  - Structured diagnostics: the PR adds IndexDecisionCode and exposes it in planner trace and gfql_explain(). decision_reason remains human-readable, while tests can assert stable codes such as policy-off, uncovered shape, or cost decline.
  - Normal query semantics: index_policy="force" does not require an index for correctness. It overrides the cost gate only for index-coverable shapes; unsupported or unavailable index cases still use the scan path. The review added regression coverage for no resident index, missing graph columns, and
    automatic decline—with scan/index result parity.

  - The earlier awkwardness was partly diagnostic: index_policy="off" produced no planner trace at all. #1840 now synthesizes top-level decision_code="policy_off" and decision_reason="policy=off" without changing execution.

  So the intended model is now: indexes affect optimization choice and explainability, not results. “Force” is an explicit performance/debugging control, not a correctness requirement.

  The deeper follow-up still makes sense: establish a small stable diagnostic taxonomy across GFQL planner decisions, with structured codes as the contract and prose only for people. #1840 is green and owner-merge-only.