refactor(tasks): share auxiliary model-role resolution on Task

[ethan-scitix]

Type

• refactor — code restructuring, no behavior change (one unreachable error-ordering corner, called out below)

Summary

• Eight tasks each carried their own _resolve_grader / _resolve_extractor. Normalising the role name away, seven are byte-identical; AGIEval's differs only because its builder also needs the candidate model.
• The declaration half of the role contract was already shared (Task._bind_role_requirement); only the resolution half was copied. So the models_by_role protocol — pooled role model, both-supplied rejection, missing-role message — had eight owners that must move together, and the next grader-bearing benchmark would have added a ninth.
• Adds Task._resolve_role_model(role, configured, models_by_role, build=...) and routes all eight through it. build takes configured and returns the Model, so each task keeps its own constructor and its own "you must supply one" message — the part that legitimately differs (AGIEval admits the self sentinel and explains its 26-point extractor spread; each grader task explains its own scoring dependency). The seven grader tasks pass self._build_grader directly; AGIEval wraps it only to add the candidate model.
• A type parameter ties the two arguments together — configured: T against build: Callable[[T], Model] — so configured is typed by whatever the builder accepts rather than object, and the value is not threaded through the call twice. Threading it twice was how a mistyped configured could slip past the both-supplied guard and let a pooled model win silently; ty now rejects a mismatched pairing.
• Both halves of the contract get direct unit tests. _bind_role_requirement had none, and its missing-binding branch is unreachable from model_requirements_for (which picks the role out of the bindings it was handed), so that message and its a/an agreement were entirely unasserted — even though all eight tasks name a literal role and can miss.
• Retires a third copy of requires must be TaskRequirements: TaskModelRequirement.__post_init__ owns it, and the copies in _bind_model_requirements / _bind_role_requirement each sat in front of a construction that re-checks the same thing. The two class-named variants stay — they validate the requires ClassVar, a different contract.
• Net −76 lines of production code (+166 in tests).

The one behaviour exception

Everything about the shared helper is byte-identical to the code it replaces. The exception is the retired type check: a call invalid in two ways at once now reports the binding problem instead of the type problem — _bind_role_requirement(ctx, "grader", <not TaskRequirements>) with no grader binding raises the missing-binding ValueError, and model_requirements_for with a bad requires ClassVar and no bindings raises the no-candidate ValueError.

Every singly-invalid call is unchanged, including a bad requires with a resolvable binding, which still raises the identical TypeError from __post_init__. Neither corner is reachable in production: requires always arrives as cls.requires, already rejected earlier by the two class-named guards (sieval/core/tasks/meta.py at decoration, _validate_model_requirements at construction).

Related Issues

Refs #25 — follow-up from the PR #45 review.

Test Plan

Automated

• Lint/format clean (ruff check && ruff format --check)
• Type check clean (ty check)
• Unit tests pass (pdm run pytest) — 5186 passed; preflight 25 PASS, no FAIL/WARN; sync_package_stubs.py --check and sync_meta_index.py --check both clean

Manual

• Behaviour pinned against the pre-refactor code. All eight tasks × six supply combinations (both supplied / missing role / pooled present / wrong role key / direct / neither) driven through both trees and diffed: 48/48 rows identical, exception chaining included. Both resolution entry points are classmethods, so this needs no dataset or model fixtures.

• Mutation-tested the shared helper, because a green suite after a move refactor proves only that nothing imports the dead code. Three mutations against Task._resolve_role_model, all caught:

  mutation	result
  remove the both-supplied guard	9 failed — one per task, plus the core test
  make it ignore models_by_role	27 failed — three per task, plus three core
  mis-key the role lookup	9 failed — one per task, plus the core test

  The per-task failure counts are the point: all eight tasks genuinely execute the shared path, rather than passing on leftovers of their own.

• Mutation-tested the declaration half, now that it has tests. Dropping the vowel branch from the a/an article, letting source_task inherit a parent's meta, dropping the role guard, dropping the context guard, and collapsing source_task to the bare class name are 5/5 caught, each by the intended test.

• Verified no lingering references to the removed methods anywhere in the tree, including .pyi stubs.

Checklist

Required (all PRs)

• PR title follows conventional format (type(scope): description)
• No internal paths, credentials, or personal info in committed files
• AI-generated code has AI-Generated Code - <model> (<provider>) in module docstring — no new modules; all touched files already carry theirs
• No new upper-layer dependencies added to core/ — the helper lives on Task in core/tasks/ and imports nothing new beyond collections.abc.Callable
• Deleted code verified — no remaining call sites depend on it