[B Sainath Reddy (Sainath-Reddy7)]

Description

Implements the P311-03 TargetConfiguration.ensure_can_handle focused case from #3166 (reserved in the table, due 2026-11-10).

ensure_can_handle checked only UnsupportedCapabilityBehavior.RAISE by equality; every other value — ADAPT and anything a future enum revision adds — fell through to the same generic error, so a new member would silently dispatch to the ADAPT path with no type-check signal. This replaces the check with explicit RAISE/ADAPT dispatch plus a TYPE_CHECKING-only assert_never guard, the same pattern as the merged human_labeled_dataset dispatch (#3830).

Unchanged, per the item's constraints:

• native-support and configured-normalizer early returns;
• missing-policy handling (KeyError → the "no handling policy exists" error);
• both existing error messages, byte-identical;
• the historical runtime fallback for values outside the declared enum (the ADAPT error);
• open string, custom-callable and provider-extension dispatch.

Tests

• New test_ensure_can_handle_unknown_behavior_keeps_historical_fallback pins the fallback with an out-of-enum behavior value (class-level patch, since CapabilityHandlingPolicy is frozen).
• Existing RAISE / missing-policy / ADAPT-without-normalizer / override tests cover both explicit branches and the preserved messages.
• tests/unit/prompt_target/target/test_target_configuration.py: 40/40 pass locally; ty check on both changed files: all checks passed.

Checklist

• Claim recorded in the Python 3.11 adoption opportunities: claim one improvement at a time #3166 reservation table before opening (P311-03, due 2026-11-10)
• PR focused on the single reserved case; issue linked
• Behavior/type-checking coverage added

AI assistance disclosure: prepared with an AI coding agent (GLM-5.3) under my direction; I reviewed each line, ran the suite and type checks locally, and stand behind the change.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.