feat: add candidate-ID alignment filtering for query generation

[saschagobel]

Summary

Introduce a deterministic filtering step for candidate-ID alignment in the synthetic query generation workflow. This enforces positional agreement between expected candidate IDs and LLM outputs.

Key changes

• Add core/querygen/filtering.py:
  • filter_aligned_candidate_ids() for positional candidate-ID reconciliation
  • keeps only items whose candidate_id matches the expected ID at the same position
  • drops misaligned items without attempting reordering or heuristic repair
  • works for both planning (QueryBlueprint) and realization (RealizedQuery) outputs via a shared candidate_id field

Design notes

• Alignment is treated as a hard positional contract:

  • shifted or mismatched IDs are considered invalid and are dropped
  • no attempt is made to repair drift, as this can silently corrupt downstream joins

• This helper operates as a deterministic aggregate step:

  • not applied per batch
  • intended for use after concatenating stage outputs

Orchestration note

The intended call pattern in api/querygen.py is:

• stage 1 (planning)
• filtering (against pre-defined candidate IDs)
• deduplication
• stage 2 (realization)
• filtering (against post–stage-1 selected candidate IDs)

Status

Ready for review.

[lramir14]

Looks good to me. The helper is simple, deterministic, and the tests cover the intended positional alignment behavior well. Only a minor non-blocking docstring nit from my side.

[lramir14]

Re-reviewed after the latest commit. The docstring concern is addressed, and the implementation matches the intended deterministic positional filtering behavior described in the issue. Approving, and will proceed with the merge.