TASK PLAN — ab-reward-registry-b3b8

• Parent design: docs/DESIGN-qu100-ab-testing.md (§4.2, §10.3, §11.2) — approved 2026-07-03
• Priority: P1 · Depends on: none · PR base: main · Effort: M

1. Problem¶

The A/B substrate must answer "is the challenger better?" — but better by what objective? Total return, Sharpe, dodged-loss, and drawdown give different winners. Today research/rewards/ is a stub: register(name, fn) with an empty REGISTRY and an implicit TradeRecord → float shape. There is no way to declare an objective's role (the thing being optimized vs a guardrail that blocks promotion), no input typing (a trade-series reward applied to a screener basket would silently compute nonsense), and no screener-shaped rewards at all.

2. The fix¶

@register("sharpe", input_type="basket", role="primary", direction="increase")
def sharpe(outcomes: BasketOutcomes) -> float: ...

REGISTRY ── keyed by name ──► {fn, input_type, role, direction, threshold}
             score(candidate_type, reward_name) → refuses input_type mismatch

• register becomes a decorator factory taking input_type (basket | trades), role (primary | guardrail | secondary), direction, and (guardrails) threshold. The as-built TradeRecord → float becomes the trades input case — existing signature is a stub with no callers, so this is safe.
• Define BasketOutcomes (frozen dataclass, pinned in design §10.3): days: list[BasketDay]; BasketDay = {date, symbols (rank order), fwd_return: {H → {symbol → float|None}}, regime}. None near window end, never 0.
• Ship the screener reward set: total_return, sharpe, hit_rate, max_drawdown (guardrail), turnover (guardrail), dodged_loss. Ratio rewards compose two aggregations.
• The registry refuses to score a candidate with a reward of the wrong input_type — a loud ValueError, no silent mis-scoring.
• Rewards are pure, deterministic, side-effect-free.
• A guardrail evaluation helper flags a breach (value vs threshold+direction); the promote-time gate consuming it is ab-registry-promote-84a7's scope.

3. Expected files¶

• src/rainier/research/rewards/__init__.py — decorator factory + registry + refusal logic.
• src/rainier/research/rewards/basket.py — BasketOutcomes/BasketDay + the screener reward set.
• tests/research/test_rewards.py.

4. Test plan (one line each)¶

• Register a new basket reward → present in registry, selectable by name, metadata (role/direction) intact.
• A trades reward scoring a basket candidate → ValueError (and vice versa).
• Each shipped reward: hand-computed fixture basket → exact expected value.
• fwd_return=None entries excluded from aggregation, never treated as 0.
• Guardrail helper: value breaching threshold+direction → flagged; non-breach → clean.
• Determinism: same BasketOutcomes → identical value across two calls.

5. Non-goals¶

• No promote-time gating logic (ab-registry-promote-84a7).
• No evaluator/replay code (ab-replay-evaluator-edb5) — fixtures construct BasketOutcomes by hand.
• No LLM/trades reward implementations beyond keeping the input-type seam working.
• No scorecard schema work (ab-experiment-contracts-5a0f).

6. Worker contract¶

Per the Subagent Dispatch Contract (~/.claude/CLAUDE.md): unit tests with the feature; codex + /review loops to clean; PR against main; PR URL in the return message.