feat: include selected variant key in flag results

[gagantrivedi]

WIP / draft. Depends on Flagsmith/flagsmith#7704 (canonical schema change) merging first — the generated type files reference those schemas. Part of the multivariate variant key work (Flagsmith/flagsmith#7698, Flagsmith/flagsmith#7699).

Changes

When a multivariate variant wins the percentage split, its key — a stable, human-readable identifier defined on the multivariate option and delivered via the environment document — is now exposed as variant in the FlagResult:

{
  "name": "checkout_button",
  "enabled": true,
  "value": "blue",
  "reason": "SPLIT; weight=30",
  "variant": "control"
}

• flag_engine/context/types.py (generated): FeatureValue gains key: NotRequired[str]
• flag_engine/result/types.py (generated): FlagResult gains variant: NotRequired[str]
• flag_engine/segments/evaluator.py: get_flag_result_from_context() carries the winning variant's key into the result; omitted when no variant is selected or the variant has no key (consistent with the schemas, and maps 1:1 to OpenFeature's ResolutionDetails.variant — None/undefined at that layer)

No change to selection logic, hashing, or variant ordering — purely an additive passthrough. This is a feat: commit, so release-please will cut a minor (10.2.0).

How did you test this code?

TDD — the new parametrised test in tests/unit/segments/test_segments_evaluator.py covers:

• keyed variant selected → variant present in the result
• unkeyed variant selected → variant omitted
• no variant selected (control/default) → variant omitted

Full suite: 378 passed, including the shared engine-test-data corpus untouched — keyless documents evaluate identically, proving backwards compatibility. mypy (strict), black, flake8, isort all clean.

The generated type changes were verified by running datamodel-code-generator 0.33.0 against the updated schemas and confirming the emitted field shapes match.

[github-actions]

File	Coverage		Missing
All files	100%	✅

Minimum allowed coverage is 100%

Generated by 🐒 cobertura-action against b9b4d1f

[codspeed-hq]

Merging this PR will not alter performance

✅ 1 untouched benchmark

---

_{Comparing feat/multivariate-variant-key (b9b4d1f) with main (ef90a90)}