feat: add core chargeback environment

__init__.py

@@ -0,0 +1,19 @@
+"""ChargebackOps OpenEnv package."""
+
+from .client import ChargebackOpsEnv
+from .models import (
+    BaselineRunResult,
+    ChargebackOpsAction,
+    ChargebackOpsObservation,
+    ChargebackOpsState,
+    GraderReport,
+)
+
+__all__ = [
+    "BaselineRunResult",
+    "ChargebackOpsAction",
+    "ChargebackOpsEnv",
+    "ChargebackOpsObservation",
+    "ChargebackOpsState",
+    "GraderReport",
+]

client.py

@@ -0,0 +1,88 @@
+"""WebSocket client for ChargebackOps."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from openenv.core import EnvClient
+from openenv.core.client_types import StepResult
+
+from .models import (
+    ActionTraceItem,
+    BaselineRunResult,
+    CaseQueueItem,
+    CaseResolutionState,
+    ChargebackOpsAction,
+    ChargebackOpsObservation,
+    ChargebackOpsState,
+    EvidenceCard,
+    GraderReport,
+    PolicyView,
+    VisibleCase,
+)
+
+
+def _parse_evidence(payload: dict[str, Any]) -> EvidenceCard:
+    return EvidenceCard(**payload)
+
+
+def _parse_policy(payload: dict[str, Any] | None) -> PolicyView | None:
+    if payload is None:
+        return None
+    return PolicyView(**payload)
+
+
+def _parse_visible_case(payload: dict[str, Any] | None) -> VisibleCase | None:
+    if payload is None:
+        return None
+    data = dict(payload)
+    data["retrieved_evidence"] = [
+        _parse_evidence(item) for item in data.get("retrieved_evidence", [])
+    ]
+    data["attached_evidence"] = [
+        _parse_evidence(item) for item in data.get("attached_evidence", [])
+    ]
+    data["policy"] = _parse_policy(data.get("policy"))
+    return VisibleCase(**data)
+
+
+def _parse_grader(payload: dict[str, Any] | None) -> GraderReport | None:
+    if payload is None:
+        return None
+    return GraderReport(**payload)
+
+
+class ChargebackOpsEnv(
+    EnvClient[ChargebackOpsAction, ChargebackOpsObservation, ChargebackOpsState]
+):
+    """Typed client for the ChargebackOps environment."""
+
+    def _step_payload(self, action: ChargebackOpsAction) -> dict[str, Any]:
+        return action.model_dump()
+
+    def _parse_result(self, payload: dict[str, Any]) -> StepResult[ChargebackOpsObservation]:
+        obs_data = dict(payload.get("observation", {}))
+        obs_data["queue"] = [CaseQueueItem(**item) for item in obs_data.get("queue", [])]
+        obs_data["visible_case"] = _parse_visible_case(obs_data.get("visible_case"))
+        obs_data["grader_report"] = _parse_grader(obs_data.get("grader_report"))
+        observation = ChargebackOpsObservation(
+            **obs_data,
+            done=payload.get("done", False),
+            reward=payload.get("reward"),
+        )
+        return StepResult(
+            observation=observation,
+            reward=payload.get("reward"),
+            done=payload.get("done", False),
+        )
+
+    def _parse_state(self, payload: dict[str, Any]) -> ChargebackOpsState:
+        data = dict(payload)
+        data["queue_state"] = [
+            CaseResolutionState(**item) for item in data.get("queue_state", [])
+        ]
+        data["action_history"] = [
+            ActionTraceItem(**item) for item in data.get("action_history", [])
+        ]
+        data["grader_report"] = _parse_grader(data.get("grader_report"))
+        return ChargebackOpsState(**data)

episode_store.py

@@ -0,0 +1,33 @@
+"""Thread-safe storage for completed episode grading reports."""
+
+from __future__ import annotations
+
+from threading import Lock
+
+try:
+    from .models import GraderReport
+except ImportError:  # pragma: no cover
+    from models import GraderReport
+
+_LOCK = Lock()
+_REPORTS: dict[str, GraderReport] = {}
+_LATEST_EPISODE_ID: str | None = None
+
+
+def record_report(report: GraderReport) -> None:
+    """Store a finished grading report."""
+
+    global _LATEST_EPISODE_ID
+    with _LOCK:
+        _REPORTS[report.episode_id] = report
+        _LATEST_EPISODE_ID = report.episode_id
+
+
+def get_report(episode_id: str | None = None) -> GraderReport | None:
+    """Return a report by id or the latest completed one."""
+
+    with _LOCK:
+        key = episode_id or _LATEST_EPISODE_ID
+        if key is None:
+            return None
+        return _REPORTS.get(key)

grading.py

@@ -0,0 +1,137 @@
+"""Deterministic grading logic for ChargebackOps."""
+
+from __future__ import annotations
+
+try:
+    from .models import CaseScoreBreakdown, GraderReport
+    from .simulation import CaseProgress, InternalCase, TaskScenario
+except ImportError:  # pragma: no cover
+    from models import CaseScoreBreakdown, GraderReport
+    from simulation import CaseProgress, InternalCase, TaskScenario
+
+
+def _ratio(numerator: int, denominator: int) -> float:
+    if denominator <= 0:
+        return 1.0
+    return max(0.0, min(1.0, numerator / denominator))
+
+
+def score_case(
+    case: InternalCase,
+    progress: CaseProgress,
+    step_count: int,
+) -> CaseScoreBreakdown:
+    """Score one case deterministically."""
+
+    final_resolution = progress.final_resolution or "unresolved"
+    required_attached = len(
+        set(progress.attached_evidence_ids).intersection(case.required_evidence_ids)
+    )
+    helpful_attached = len(
+        set(progress.attached_evidence_ids).intersection(case.helpful_evidence_ids)
+    )
+    harmful_attached = len(
+        set(progress.attached_evidence_ids).intersection(case.harmful_evidence_ids)
+    )
+
+    if final_resolution == case.optimal_strategy:
+        strategy_correctness = 1.0
+    elif final_resolution in case.acceptable_strategies:
+        strategy_correctness = 0.55
+    else:
+        strategy_correctness = 0.0
+
+    if final_resolution == "contest":
+        base_evidence_quality = 0.7 * _ratio(required_attached, len(case.required_evidence_ids))
+        bonus = 0.3 * _ratio(helpful_attached, max(1, len(case.helpful_evidence_ids)))
+        penalty = 0.25 * harmful_attached
+        evidence_quality = max(0.0, min(1.0, base_evidence_quality + bonus - penalty))
+        packet_validity = (
+            1.0
+            if required_attached == len(case.required_evidence_ids) and harmful_attached == 0
+            else 0.0
+        )
+    else:
+        if final_resolution in {"accept_chargeback", "issue_refund"}:
+            evidence_quality = 1.0 if helpful_attached == 0 and harmful_attached == 0 else 0.7
+            packet_validity = 1.0
+        else:
+            evidence_quality = 0.0
+            packet_validity = 0.0
+
+    deadline_compliance = 1.0
+    if final_resolution == "unresolved":
+        deadline_compliance = 0.0
+    elif step_count > case.deadline_step:
+        deadline_compliance = 0.0
+
+    wasted_actions = progress.duplicate_queries + progress.invalid_actions
+    efficiency = max(0.0, 1.0 - min(0.9, wasted_actions * 0.1 + progress.submit_attempts * 0.05))
+
+    if final_resolution == case.optimal_strategy:
+        outcome_quality = 1.0
+    elif final_resolution in case.acceptable_strategies:
+        outcome_quality = 0.6
+    else:
+        outcome_quality = 0.0
+
+    weighted_score = (
+        0.25 * strategy_correctness
+        + 0.25 * evidence_quality
+        + 0.15 * packet_validity
+        + 0.15 * deadline_compliance
+        + 0.10 * efficiency
+        + 0.10 * outcome_quality
+    )
+
+    note_parts = [case.resolution_summary]
+    if harmful_attached:
+        note_parts.append("Harmful evidence weakened the case.")
+    if final_resolution == "unresolved":
+        note_parts.append("Case was never resolved.")
+    elif step_count > case.deadline_step:
+        note_parts.append("Resolution happened after the deadline.")
+
+    return CaseScoreBreakdown(
+        case_id=case.case_id,
+        strategy_correctness=round(strategy_correctness, 4),
+        evidence_quality=round(evidence_quality, 4),
+        packet_validity=round(packet_validity, 4),
+        deadline_compliance=round(deadline_compliance, 4),
+        efficiency=round(efficiency, 4),
+        outcome_quality=round(outcome_quality, 4),
+        weighted_score=round(weighted_score * case.weight, 4),
+        final_resolution=final_resolution,
+        notes=" ".join(note_parts),
+    )
+
+
+def grade_episode(
+    task: TaskScenario,
+    progress_by_case: dict[str, CaseProgress],
+    step_count: int,
+    episode_id: str,
+    completed: bool,
+) -> GraderReport:
+    """Grade a full episode."""
+
+    case_reports = [
+        score_case(case, progress_by_case[case.case_id], step_count)
+        for case in task.cases
+    ]
+    total_weight = sum(case.weight for case in task.cases)
+    total_score = sum(report.weighted_score for report in case_reports)
+    normalized = 0.0 if total_weight == 0 else min(1.0, total_score / total_weight)
+    summary = (
+        f"Resolved {sum(1 for report in case_reports if report.final_resolution != 'unresolved')}/"
+        f"{len(case_reports)} cases with normalized score {normalized:.3f}."
+    )
+    return GraderReport(
+        episode_id=episode_id,
+        task_id=task.task_id,
+        total_score=round(total_score, 4),
+        normalized_score=round(normalized, 4),
+        completed=completed,
+        case_reports=case_reports,
+        summary=summary,
+    )

models.py

@@ -0,0 +1,218 @@
+"""Typed models for the ChargebackOps OpenEnv environment."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from openenv.core.env_server.types import Action, Observation, State
+from pydantic import BaseModel, Field
+
+SystemName = Literal["orders", "payment", "shipping", "support", "refunds", "risk"]
+StrategyName = Literal["contest", "accept_chargeback", "issue_refund"]
+ActionType = Literal[
+    "select_case",
+    "inspect_case",
+    "query_system",
+    "retrieve_policy",
+    "add_evidence",
+    "remove_evidence",
+    "set_strategy",
+    "submit_representment",
+    "resolve_case",
+]
+
+
+class CaseQueueItem(BaseModel):
+    """Queue-level summary of a chargeback case."""
+
+    case_id: str
+    amount: float
+    currency: str
+    reason_code: str
+    status: str
+    summary: str
+    deadline_step: int
+    steps_until_deadline: int
+
+
+class EvidenceCard(BaseModel):
+    """Evidence snippet visible to the agent."""
+
+    evidence_id: str
+    source_system: SystemName
+    title: str
+    summary: str
+    attached: bool = False
+
+
+class PolicyView(BaseModel):
+    """Visible reason-code policy guidance."""
+
+    reason_code: str
+    guidance: str
+    required_evidence: list[str] = Field(default_factory=list)
+    recommended_strategy: StrategyName
+
+
+class VisibleCase(BaseModel):
+    """Current workspace for the selected case."""
+
+    case_id: str
+    order_id: str
+    customer_id: str
+    amount: float
+    currency: str
+    reason_code: str
+    status: str
+    current_strategy: StrategyName | None = None
+    summary: str
+    inspection_notes: str | None = None
+    systems_revealed: list[SystemName] = Field(default_factory=list)
+    retrieved_evidence: list[EvidenceCard] = Field(default_factory=list)
+    attached_evidence: list[EvidenceCard] = Field(default_factory=list)
+    policy: PolicyView | None = None
+    submission_status: str | None = None
+
+
+class TaskSummary(BaseModel):
+    """Metadata for a built-in task."""
+
+    task_id: str
+    title: str
+    difficulty: Literal["easy", "medium", "hard"]
+    objective: str
+    description: str
+    max_steps: int
+    case_count: int
+
+
+class ActionTraceItem(BaseModel):
+    """Compact action history row."""
+
+    step_index: int
+    action_type: str
+    case_id: str | None = None
+    outcome: str
+    reward: float
+
+
+class CaseResolutionState(BaseModel):
+    """Public case state in the current episode."""
+
+    case_id: str
+    status: str
+    current_strategy: StrategyName | None = None
+    resolved: bool = False
+    steps_until_deadline: int
+
+
+class CaseScoreBreakdown(BaseModel):
+    """Per-case grading breakdown."""
+
+    case_id: str
+    strategy_correctness: float
+    evidence_quality: float
+    packet_validity: float
+    deadline_compliance: float
+    efficiency: float
+    outcome_quality: float
+    weighted_score: float
+    final_resolution: str
+    notes: str
+
+
+class GraderReport(BaseModel):
+    """Episode-level deterministic grade report."""
+
+    episode_id: str
+    task_id: str
+    total_score: float
+    normalized_score: float
+    completed: bool
+    case_reports: list[CaseScoreBreakdown] = Field(default_factory=list)
+    summary: str
+
+
+class BaselineTaskResult(BaseModel):
+    """Baseline score for one task."""
+
+    task_id: str
+    title: str
+    score: float
+    steps_used: int
+    final_status: str
+
+
+class BaselineRunResult(BaseModel):
+    """Aggregate baseline result payload."""
+
+    provider: str
+    model_name: str
+    mode: str
+    provider_calls_attempted: int = 0
+    provider_calls_succeeded: int = 0
+    provider_errors: dict[str, int] = Field(default_factory=dict)
+    task_results: list[BaselineTaskResult]
+    average_score: float
+
+
+class TasksResponse(BaseModel):
+    """Payload returned by /tasks."""
+
+    tasks: list[TaskSummary]
+    action_schema: dict[str, Any]
+
+
+class ChargebackOpsAction(Action):
+    """Action schema for ChargebackOps."""
+
+    action_type: ActionType
+    case_id: str | None = Field(default=None, description="Target case id when applicable")
+    system_name: SystemName | None = Field(
+        default=None,
+        description="System to query when action_type is query_system",
+    )
+    evidence_ids: list[str] = Field(
+        default_factory=list,
+        description="Evidence ids to attach or remove",
+    )
+    strategy: StrategyName | None = Field(
+        default=None,
+        description="Strategy to set or use when resolving a case",
+    )
+    note: str | None = Field(
+        default=None,
+        description="Optional short rationale for the action",
+    )
+
+
+class ChargebackOpsObservation(Observation):
+    """Observation returned by reset() and step()."""
+
+    task_id: str
+    task_title: str
+    difficulty: Literal["easy", "medium", "hard"]
+    objective: str
+    selected_case_id: str | None = None
+    queue: list[CaseQueueItem] = Field(default_factory=list)
+    visible_case: VisibleCase | None = None
+    last_action_result: str = ""
+    available_actions: list[str] = Field(default_factory=list)
+    steps_remaining: int
+    progress_score: float = 0.0
+    grader_report: GraderReport | None = None
+
+
+class ChargebackOpsState(State):
+    """Extended environment state returned by state()."""
+
+    task_id: str
+    task_title: str
+    difficulty: Literal["easy", "medium", "hard"]
+    objective: str
+    selected_case_id: str | None = None
+    queue_state: list[CaseResolutionState] = Field(default_factory=list)
+    action_history: list[ActionTraceItem] = Field(default_factory=list)
+    latest_grade: float | None = None
+    grader_report: GraderReport | None = None
+    completed: bool = False

openenv.yaml

@@ -0,0 +1,7 @@
+spec_version: 1
+name: chargeback_ops
+type: space
+runtime: fastapi
+app: server.app:app
+port: 8000
+description: Merchant dispute handling and chargeback representment environment

pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openenv-chargeback_ops"
+version = "0.1.0"
+description = "ChargebackOps: a real-world OpenEnv environment for merchant dispute handling."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "anthropic>=0.51.0",
+    "fastapi>=0.135.0",
+    "openai>=2.30.0",
+    "openenv-core[core]>=0.2.2",
+    "pydantic>=2.12.0",
+    "python-dotenv>=1.0.1",
+    "uvicorn>=0.42.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "httpx>=0.28.0",
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[project.scripts]
+server = "chargeback_ops.server.app:main"
+chargebackops-baseline = "chargeback_ops.baseline_runner:main"
+
+[tool.setuptools]
+include-package-data = true
+packages = ["chargeback_ops", "chargeback_ops.server"]
+package-dir = { "chargeback_ops" = ".", "chargeback_ops.server" = "server" }
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

server/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Chargeback Ops environment server components."""
+
+from .chargeback_ops_environment import ChargebackOpsEnvironment
+
+__all__ = ["ChargebackOpsEnvironment"]

server/chargeback_ops_environment.py

@@ -0,0 +1,570 @@
+"""Core environment implementation for ChargebackOps."""
+
+from __future__ import annotations
+
+from uuid import uuid4
+
+from openenv.core.env_server.interfaces import Environment
+
+try:
+    from ..episode_store import record_report
+    from ..grading import grade_episode
+    from ..models import (
+        ActionTraceItem,
+        CaseQueueItem,
+        CaseResolutionState,
+        ChargebackOpsAction,
+        ChargebackOpsObservation,
+        ChargebackOpsState,
+        EvidenceCard,
+        PolicyView,
+        VisibleCase,
+    )
+    from ..simulation import ActionRecord, CaseProgress, InternalCase, get_task
+except ImportError:  # pragma: no cover
+    from episode_store import record_report
+    from grading import grade_episode
+    from models import (
+        ActionTraceItem,
+        CaseQueueItem,
+        CaseResolutionState,
+        ChargebackOpsAction,
+        ChargebackOpsObservation,
+        ChargebackOpsState,
+        EvidenceCard,
+        PolicyView,
+        VisibleCase,
+    )
+    from simulation import ActionRecord, CaseProgress, InternalCase, get_task
+
+
+class ChargebackOpsEnvironment(
+    Environment[ChargebackOpsAction, ChargebackOpsObservation, ChargebackOpsState]
+):
+    """Synthetic merchant chargeback representment environment."""
+
+    SUPPORTS_CONCURRENT_SESSIONS: bool = True
+
+    def __init__(self):
+        super().__init__()
+        self._task = get_task("goods_not_received_easy")
+        self._selected_case_id: str | None = None
+        self._last_action_result = "Environment initialized."
+        self._action_history: list[ActionRecord] = []
+        self._progress_by_case: dict[str, CaseProgress] = {}
+        self._state = ChargebackOpsState(
+            episode_id=str(uuid4()),
+            step_count=0,
+            task_id=self._task.task_id,
+            task_title=self._task.title,
+            difficulty=self._task.difficulty,
+            objective=self._task.objective,
+        )
+        self._done = False
+        self._latest_report = None
+        self._reset_task_state()
+
+    def _reset_task_state(self) -> None:
+        self._progress_by_case = {
+            case.case_id: CaseProgress() for case in self._task.cases
+        }
+        self._selected_case_id = None
+        self._action_history = []
+        self._last_action_result = f"{self._task.title} ready."
+        self._done = False
+        self._latest_report = None
+
+    def reset(
+        self,
+        seed: int | None = None,
+        episode_id: str | None = None,
+        **kwargs,
+    ) -> ChargebackOpsObservation:
+        del seed
+        task_id = kwargs.get("task_id", "goods_not_received_easy")
+        self._task = get_task(task_id)
+        self._state = ChargebackOpsState(
+            episode_id=episode_id or str(uuid4()),
+            step_count=0,
+            task_id=self._task.task_id,
+            task_title=self._task.title,
+            difficulty=self._task.difficulty,
+            objective=self._task.objective,
+        )
+        self._reset_task_state()
+        return self._build_observation(reward=0.0, done=False)
+
+    def step(
+        self,
+        action: ChargebackOpsAction,
+        timeout_s: float | None = None,
+        **kwargs,
+    ) -> ChargebackOpsObservation:
+        del timeout_s, kwargs
+        if self._done:
+            return self._build_observation(
+                reward=-0.1,
+                done=True,
+                result="Episode already completed. Reset to start another task.",
+            )
+
+        self._state.step_count += 1
+        reward = 0.0
+        result = ""
+
+        try:
+            reward, result = self._apply_action(action)
+        except ValueError as exc:
+            reward = -0.12
+            result = str(exc)
+            case_id = action.case_id or self._selected_case_id
+            if case_id and case_id in self._progress_by_case:
+                self._progress_by_case[case_id].invalid_actions += 1
+
+        reward += self._apply_deadline_penalties()
+        done = self._check_done()
+        if done:
+            report = grade_episode(
+                self._task,
+                self._progress_by_case,
+                self._state.step_count,
+                self._state.episode_id or "",
+                completed=self._all_cases_resolved(),
+            )
+            self._latest_report = report
+            self._state.latest_grade = report.normalized_score
+            self._state.grader_report = report
+            self._state.completed = True
+            record_report(report)
+            reward += 0.5 * report.normalized_score
+        else:
+            self._state.latest_grade = self._estimated_progress_score()
+            self._state.completed = False
+
+        self._last_action_result = result
+        self._action_history.append(
+            ActionRecord(
+                step_index=self._state.step_count,
+                action_type=action.action_type,
+                case_id=action.case_id or self._selected_case_id,
+                outcome=result,
+                reward=round(reward, 4),
+            )
+        )
+        return self._build_observation(
+            reward=round(reward, 4),
+            done=done,
+            result=result,
+        )
+
+    def _apply_action(self, action: ChargebackOpsAction) -> tuple[float, str]:
+        if action.action_type == "select_case":
+            return self._select_case(action.case_id)
+        case = self._require_case(action.case_id)
+
+        if action.action_type == "inspect_case":
+            return self._inspect_case(case)
+        if action.action_type == "query_system":
+            return self._query_system(case, action.system_name)
+        if action.action_type == "retrieve_policy":
+            return self._retrieve_policy(case)
+        if action.action_type == "add_evidence":
+            return self._add_evidence(case, action.evidence_ids)
+        if action.action_type == "remove_evidence":
+            return self._remove_evidence(case, action.evidence_ids)
+        if action.action_type == "set_strategy":
+            return self._set_strategy(case, action.strategy)
+        if action.action_type == "submit_representment":
+            return self._submit_representment(case)
+        if action.action_type == "resolve_case":
+            return self._resolve_case(case, action.strategy)
+        raise ValueError(f"Unsupported action_type '{action.action_type}'.")
+
+    def _select_case(self, case_id: str | None) -> tuple[float, str]:
+        if not case_id:
+            raise ValueError("select_case requires case_id.")
+        case = self._lookup_case(case_id)
+        self._selected_case_id = case.case_id
+        progress = self._progress_by_case[case.case_id]
+        if progress.resolution_status != "open":
+            return -0.02, f"Case {case.case_id} is already resolved."
+        return 0.02, f"Selected case {case.case_id}."
+
+    def _inspect_case(self, case: InternalCase) -> tuple[float, str]:
+        progress = self._progress_by_case[case.case_id]
+        if progress.inspected:
+            return -0.01, f"Case {case.case_id} was already inspected."
+        progress.inspected = True
+        return 0.04, f"Inspected case {case.case_id}."
+
+    def _query_system(
+        self,
+        case: InternalCase,
+        system_name: str | None,
+    ) -> tuple[float, str]:
+        if system_name is None:
+            raise ValueError("query_system requires system_name.")
+        progress = self._progress_by_case[case.case_id]
+        if system_name in progress.revealed_systems:
+            progress.duplicate_queries += 1
+            return -0.03, f"System '{system_name}' was already queried for case {case.case_id}."
+
+        progress.revealed_systems.add(system_name)
+        new_evidence = case.evidence_by_system.get(system_name, ())
+        progress.retrieved_evidence_ids.update(item.evidence_id for item in new_evidence)
+        helpful = sum(1 for item in new_evidence if item.helpful)
+        if helpful > 0:
+            return 0.06 + 0.01 * helpful, (
+                f"Queried {system_name} for case {case.case_id}; found {len(new_evidence)} evidence items, "
+                f"including {helpful} useful ones."
+            )
+        return -0.01 if len(new_evidence) == 0 else 0.01, (
+            f"Queried {system_name} for case {case.case_id}; found {len(new_evidence)} evidence items."
+        )
+
+    def _retrieve_policy(self, case: InternalCase) -> tuple[float, str]:
+        progress = self._progress_by_case[case.case_id]
+        if progress.policy_retrieved:
+            return -0.01, f"Policy already retrieved for case {case.case_id}."
+        progress.policy_retrieved = True
+        return 0.05, f"Retrieved policy guidance for case {case.case_id}."
+
+    def _add_evidence(
+        self,
+        case: InternalCase,
+        evidence_ids: list[str],
+    ) -> tuple[float, str]:
+        if not evidence_ids:
+            raise ValueError("add_evidence requires at least one evidence id.")
+        progress = self._progress_by_case[case.case_id]
+        all_evidence = self._evidence_map(case)
+        reward = 0.0
+        added = []
+        for evidence_id in evidence_ids:
+            if evidence_id not in progress.retrieved_evidence_ids:
+                reward -= 0.04
+                continue
+            if evidence_id in progress.attached_evidence_ids:
+                reward -= 0.02
+                continue
+            progress.attached_evidence_ids.append(evidence_id)
+            added.append(evidence_id)
+            evidence = all_evidence[evidence_id]
+            if evidence.helpful:
+                reward += 0.08
+            elif evidence.harmful:
+                reward -= 0.08
+            else:
+                reward += 0.01
+        return reward if added else -0.05, (
+            f"Attached evidence {', '.join(added)} to case {case.case_id}."
+            if added
+            else f"No evidence was attached to case {case.case_id}."
+        )
+
+    def _remove_evidence(
+        self,
+        case: InternalCase,
+        evidence_ids: list[str],
+    ) -> tuple[float, str]:
+        if not evidence_ids:
+            raise ValueError("remove_evidence requires at least one evidence id.")
+        progress = self._progress_by_case[case.case_id]
+        evidence_map = self._evidence_map(case)
+        reward = 0.0
+        removed = []
+        for evidence_id in evidence_ids:
+            if evidence_id not in progress.attached_evidence_ids:
+                reward -= 0.02
+                continue
+            progress.attached_evidence_ids.remove(evidence_id)
+            removed.append(evidence_id)
+            if evidence_map[evidence_id].harmful:
+                reward += 0.05
+            elif evidence_map[evidence_id].helpful:
+                reward -= 0.03
+            else:
+                reward += 0.01
+        return reward if removed else -0.04, (
+            f"Removed evidence {', '.join(removed)} from case {case.case_id}."
+            if removed
+            else f"No evidence was removed from case {case.case_id}."
+        )
+
+    def _set_strategy(
+        self,
+        case: InternalCase,
+        strategy: str | None,
+    ) -> tuple[float, str]:
+        if strategy is None:
+            raise ValueError("set_strategy requires strategy.")
+        progress = self._progress_by_case[case.case_id]
+        progress.current_strategy = strategy
+        if strategy == case.optimal_strategy:
+            return 0.1, f"Set the optimal strategy '{strategy}' for case {case.case_id}."
+        if strategy in case.acceptable_strategies:
+            return 0.03, f"Set an acceptable fallback strategy '{strategy}' for case {case.case_id}."
+        return -0.08, f"Set a weak strategy '{strategy}' for case {case.case_id}."
+
+    def _submit_representment(self, case: InternalCase) -> tuple[float, str]:
+        progress = self._progress_by_case[case.case_id]
+        progress.submit_attempts += 1
+        if progress.current_strategy != "contest":
+            raise ValueError("submit_representment requires current strategy to be 'contest'.")
+        if progress.resolution_status != "open":
+            return -0.05, f"Case {case.case_id} is already resolved."
+
+        attached = set(progress.attached_evidence_ids)
+        missing = set(case.required_evidence_ids).difference(attached)
+        harmful = set(case.harmful_evidence_ids).intersection(attached)
+        if self._state.step_count > case.deadline_step:
+            progress.final_resolution = "contest"
+            progress.resolution_status = "lost_late"
+            return -0.2, f"Representment for case {case.case_id} was submitted after the deadline."
+        if missing:
+            progress.final_resolution = "contest"
+            progress.resolution_status = "lost_incomplete"
+            return -0.18, (
+                f"Representment for case {case.case_id} is incomplete; missing {', '.join(sorted(missing))}."
+            )
+        if harmful:
+            progress.final_resolution = "contest"
+            progress.resolution_status = "lost_harmful_evidence"
+            return -0.15, (
+                f"Representment for case {case.case_id} included harmful evidence {', '.join(sorted(harmful))}."
+            )
+
+        progress.final_resolution = "contest"
+        if case.optimal_strategy == "contest":
+            progress.resolution_status = "won"
+            return 0.2, f"Submitted a strong representment package for case {case.case_id}."
+        progress.resolution_status = "lost_contest"
+        return -0.12, f"Contested case {case.case_id}, but the case was not supportable."
+
+    def _resolve_case(
+        self,
+        case: InternalCase,
+        strategy: str | None,
+    ) -> tuple[float, str]:
+        progress = self._progress_by_case[case.case_id]
+        resolution = strategy or progress.current_strategy
+        if resolution not in {"accept_chargeback", "issue_refund"}:
+            raise ValueError("resolve_case requires strategy accept_chargeback or issue_refund.")
+        if progress.resolution_status != "open":
+            return -0.04, f"Case {case.case_id} is already resolved."
+        progress.final_resolution = resolution
+        progress.current_strategy = resolution
+        progress.resolution_status = (
+            "refunded" if resolution == "issue_refund" else "accepted_chargeback"
+        )
+        if self._state.step_count > case.deadline_step:
+            return -0.15, f"Resolved case {case.case_id} after the response deadline."
+        if resolution == case.optimal_strategy:
+            return 0.16, f"Resolved case {case.case_id} with the optimal non-contest strategy."
+        if resolution in case.acceptable_strategies:
+            return 0.06, f"Resolved case {case.case_id} with an acceptable fallback strategy."
+        return -0.12, f"Resolved case {case.case_id} with the wrong strategy."
+
+    def _apply_deadline_penalties(self) -> float:
+        penalty = 0.0
+        for case in self._task.cases:
+            progress = self._progress_by_case[case.case_id]
+            if progress.resolution_status == "open" and self._state.step_count > case.deadline_step:
+                if not progress.deadline_penalized:
+                    progress.deadline_penalized = True
+                    penalty -= 0.15
+        return penalty
+
+    def _check_done(self) -> bool:
+        if self._all_cases_resolved():
+            self._done = True
+        elif self._state.step_count >= self._task.max_steps:
+            self._done = True
+        return self._done
+
+    def _all_cases_resolved(self) -> bool:
+        return all(
+            progress.resolution_status != "open"
+            for progress in self._progress_by_case.values()
+        )
+
+    def _lookup_case(self, case_id: str) -> InternalCase:
+        for case in self._task.cases:
+            if case.case_id == case_id:
+                return case
+        raise ValueError(f"Unknown case_id '{case_id}'.")
+
+    def _require_case(self, case_id: str | None) -> InternalCase:
+        target_case_id = case_id or self._selected_case_id
+        if target_case_id is None:
+            raise ValueError("Select a case before taking this action.")
+        return self._lookup_case(target_case_id)
+
+    def _evidence_map(self, case: InternalCase):
+        return {
+            item.evidence_id: item
+            for items in case.evidence_by_system.values()
+            for item in items
+        }
+
+    def _build_queue(self) -> list[CaseQueueItem]:
+        queue = []
+        for case in self._task.cases:
+            progress = self._progress_by_case[case.case_id]
+            queue.append(
+                CaseQueueItem(
+                    case_id=case.case_id,
+                    amount=case.amount,
+                    currency=case.currency,
+                    reason_code=case.reason_code,
+                    status=progress.resolution_status,
+                    summary=case.summary,
+                    deadline_step=case.deadline_step,
+                    steps_until_deadline=case.deadline_step - self._state.step_count,
+                )
+            )
+        return queue
+
+    def _build_visible_case(self) -> VisibleCase | None:
+        if self._selected_case_id is None:
+            return None
+        case = self._lookup_case(self._selected_case_id)
+        progress = self._progress_by_case[case.case_id]
+        evidence_map = self._evidence_map(case)
+        retrieved = [
+            EvidenceCard(
+                evidence_id=evidence_id,
+                source_system=evidence_map[evidence_id].source_system,
+                title=evidence_map[evidence_id].title,
+                summary=evidence_map[evidence_id].summary,
+                attached=evidence_id in progress.attached_evidence_ids,
+            )
+            for evidence_id in sorted(progress.retrieved_evidence_ids)
+        ]
+        attached = [
+            EvidenceCard(
+                evidence_id=evidence_id,
+                source_system=evidence_map[evidence_id].source_system,
+                title=evidence_map[evidence_id].title,
+                summary=evidence_map[evidence_id].summary,
+                attached=True,
+            )
+            for evidence_id in progress.attached_evidence_ids
+        ]
+        policy = None
+        if progress.policy_retrieved:
+            policy = PolicyView(
+                reason_code=case.reason_code,
+                guidance=case.policy_guidance,
+                required_evidence=list(case.policy_requirements),
+                recommended_strategy=case.recommended_strategy,
+            )
+        return VisibleCase(
+            case_id=case.case_id,
+            order_id=case.order_id,
+            customer_id=case.customer_id,
+            amount=case.amount,
+            currency=case.currency,
+            reason_code=case.reason_code,
+            status=progress.resolution_status,
+            current_strategy=progress.current_strategy,
+            summary=case.summary,
+            inspection_notes=case.inspection_notes if progress.inspected else None,
+            systems_revealed=sorted(progress.revealed_systems),
+            retrieved_evidence=retrieved,
+            attached_evidence=attached,
+            policy=policy,
+            submission_status=progress.resolution_status
+            if progress.resolution_status != "open"
+            else None,
+        )
+
+    def _build_available_actions(self) -> list[str]:
+        if self._done:
+            return []
+        base = ["select_case"]
+        if self._selected_case_id is None:
+            return base
+        case_progress = self._progress_by_case[self._selected_case_id]
+        if case_progress.resolution_status != "open":
+            return ["select_case"]
+        return base + [
+            "inspect_case",
+            "query_system",
+            "retrieve_policy",
+            "add_evidence",
+            "remove_evidence",
+            "set_strategy",
+            "submit_representment",
+            "resolve_case",
+        ]
+
+    def _estimated_progress_score(self) -> float:
+        report = grade_episode(
+            self._task,
+            self._progress_by_case,
+            self._state.step_count,
+            self._state.episode_id or "",
+            completed=False,
+        )
+        return report.normalized_score
+
+    def _build_observation(
+        self,
+        reward: float,
+        done: bool,
+        result: str | None = None,
+    ) -> ChargebackOpsObservation:
+        progress_score = (
+            self._latest_report.normalized_score
+            if self._latest_report is not None
+            else self._estimated_progress_score()
+        )
+        self._state.queue_state = [
+            CaseResolutionState(
+                case_id=case.case_id,
+                status=self._progress_by_case[case.case_id].resolution_status,
+                current_strategy=self._progress_by_case[case.case_id].current_strategy,
+                resolved=self._progress_by_case[case.case_id].resolution_status != "open",
+                steps_until_deadline=case.deadline_step - self._state.step_count,
+            )
+            for case in self._task.cases
+        ]
+        self._state.action_history = [
+            ActionTraceItem(
+                step_index=record.step_index,
+                action_type=record.action_type,
+                case_id=record.case_id,
+                outcome=record.outcome,
+                reward=record.reward,
+            )
+            for record in self._action_history
+        ]
+        self._state.selected_case_id = self._selected_case_id
+
+        return ChargebackOpsObservation(
+            task_id=self._task.task_id,
+            task_title=self._task.title,
+            difficulty=self._task.difficulty,
+            objective=self._task.objective,
+            selected_case_id=self._selected_case_id,
+            queue=self._build_queue(),
+            visible_case=self._build_visible_case(),
+            last_action_result=result or self._last_action_result,
+            available_actions=self._build_available_actions(),
+            steps_remaining=max(0, self._task.max_steps - self._state.step_count),
+            progress_score=round(progress_score, 4),
+            grader_report=self._latest_report,
+            done=done,
+            reward=reward,
+            metadata={
+                "reward_components": {
+                    "step_reward": reward,
+                    "progress_score": round(progress_score, 4),
+                }
+            },
+        )
+
+    @property
+    def state(self) -> ChargebackOpsState:
+        return self._state

server/requirements.txt

@@ -0,0 +1,4 @@
+anthropic>=0.51.0
+openai>=2.30.0
+openenv-core[core]>=0.2.2
+python-dotenv>=1.0.1

simulation.py

@@ -0,0 +1,598 @@
+"""Internal task definitions and runtime types for ChargebackOps."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+SystemName = Literal["orders", "payment", "shipping", "support", "refunds", "risk"]
+StrategyName = Literal["contest", "accept_chargeback", "issue_refund"]
+
+
+@dataclass(frozen=True)
+class InternalEvidence:
+    """Evidence item stored in a synthetic merchant system."""
+
+    evidence_id: str
+    source_system: SystemName
+    title: str
+    summary: str
+    helpful: bool = False
+    harmful: bool = False
+    required: bool = False
+
+
+@dataclass(frozen=True)
+class InternalCase:
+    """Synthetic chargeback case definition."""
+
+    case_id: str
+    order_id: str
+    customer_id: str
+    amount: float
+    currency: str
+    reason_code: str
+    summary: str
+    inspection_notes: str
+    deadline_step: int
+    optimal_strategy: StrategyName
+    acceptable_strategies: tuple[StrategyName, ...]
+    policy_guidance: str
+    policy_requirements: tuple[str, ...]
+    recommended_strategy: StrategyName
+    resolution_summary: str
+    weight: float
+    evidence_by_system: dict[SystemName, tuple[InternalEvidence, ...]]
+    required_evidence_ids: tuple[str, ...] = ()
+    helpful_evidence_ids: tuple[str, ...] = ()
+    harmful_evidence_ids: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class TaskScenario:
+    """One benchmark task."""
+
+    task_id: str
+    title: str
+    difficulty: Literal["easy", "medium", "hard"]
+    objective: str
+    description: str
+    max_steps: int
+    cases: tuple[InternalCase, ...]
+
+
+@dataclass
+class CaseProgress:
+    """Mutable runtime state for one case."""
+
+    inspected: bool = False
+    policy_retrieved: bool = False
+    revealed_systems: set[SystemName] = field(default_factory=set)
+    retrieved_evidence_ids: set[str] = field(default_factory=set)
+    attached_evidence_ids: list[str] = field(default_factory=list)
+    current_strategy: StrategyName | None = None
+    final_resolution: str | None = None
+    resolution_status: str = "open"
+    duplicate_queries: int = 0
+    invalid_actions: int = 0
+    submit_attempts: int = 0
+    deadline_penalized: bool = False
+    notes: list[str] = field(default_factory=list)
+
+
+@dataclass
+class ActionRecord:
+    """Runtime action history."""
+
+    step_index: int
+    action_type: str
+    case_id: str | None
+    outcome: str
+    reward: float
+
+
+def _ev(
+    evidence_id: str,
+    source_system: SystemName,
+    title: str,
+    summary: str,
+    *,
+    helpful: bool = False,
+    harmful: bool = False,
+    required: bool = False,
+) -> InternalEvidence:
+    return InternalEvidence(
+        evidence_id=evidence_id,
+        source_system=source_system,
+        title=title,
+        summary=summary,
+        helpful=helpful,
+        harmful=harmful,
+        required=required,
+    )
+
+
+TASKS: dict[str, TaskScenario] = {
+    "goods_not_received_easy": TaskScenario(
+        task_id="goods_not_received_easy",
+        title="Delivered But Disputed",
+        difficulty="easy",
+        objective="Contest a goods-not-received chargeback with the right delivery proof before the deadline.",
+        description=(
+            "A single e-commerce dispute where carrier confirmation and the order confirmation "
+            "are enough to win. The task teaches the standard representment loop."
+        ),
+        max_steps=10,
+        cases=(
+            InternalCase(
+                case_id="CB-E1",
+                order_id="ORD-7410",
+                customer_id="CUST-1001",
+                amount=129.99,
+                currency="USD",
+                reason_code="goods_not_received",
+                summary="Cardholder claims the package never arrived.",
+                inspection_notes=(
+                    "Order shipped the same day. Merchant policy requires carrier proof plus the original order confirmation "
+                    "for goods-not-received disputes."
+                ),
+                deadline_step=8,
+                optimal_strategy="contest",
+                acceptable_strategies=(),
+                policy_guidance=(
+                    "For goods-not-received disputes, prove the merchandise was fulfilled to the billed customer with "
+                    "order confirmation and carrier delivery evidence."
+                ),
+                policy_requirements=("order confirmation", "carrier delivery confirmation"),
+                recommended_strategy="contest",
+                resolution_summary="Strong delivery proof exists. Contesting should recover the funds.",
+                weight=1.0,
+                required_evidence_ids=("E1-ORDER-CONF", "E1-DELIVERY-SCAN"),
+                helpful_evidence_ids=("E1-ORDER-CONF", "E1-DELIVERY-SCAN", "E1-SUPPORT-ACK"),
+                harmful_evidence_ids=(),
+                evidence_by_system={
+                    "orders": (
+                        _ev(
+                            "E1-ORDER-CONF",
+                            "orders",
+                            "Order confirmation",
+                            "Order confirmation email and checkout receipt showing the billed customer, shipping address, and SKU.",
+                            helpful=True,
+                            required=True,
+                        ),
+                    ),
+                    "payment": (
+                        _ev(
+                            "E1-AUTH",
+                            "payment",
+                            "Authorization record",
+                            "Authorization approved and captured successfully.",
+                        ),
+                    ),
+                    "shipping": (
+                        _ev(
+                            "E1-DELIVERY-SCAN",
+                            "shipping",
+                            "Carrier delivery scan",
+                            "Carrier tracking shows delivered to the customer address two days after shipment.",
+                            helpful=True,
+                            required=True,
+                        ),
+                        _ev(
+                            "E1-SIGNATURE",
+                            "shipping",
+                            "Doorstep photo confirmation",
+                            "Carrier stored a package photo at the delivery location.",
+                            helpful=True,
+                        ),
+                    ),
+                    "support": (
+                        _ev(
+                            "E1-SUPPORT-ACK",
+                            "support",
+                            "Support ticket acknowledgement",
+                            "Customer contacted support to ask if the package was left at the front desk after delivery.",
+                            helpful=True,
+                        ),
+                    ),
+                    "refunds": (
+                        _ev(
+                            "E1-NO-REFUND",
+                            "refunds",
+                            "Refund ledger",
+                            "No refund or goodwill credit was issued before the dispute opened.",
+                        ),
+                    ),
+                    "risk": (
+                        _ev(
+                            "E1-RISK",
+                            "risk",
+                            "Risk summary",
+                            "Low-risk order with no fraud flags.",
+                        ),
+                    ),
+                },
+            ),
+        ),
+    ),
+    "fraud_signal_ambiguity": TaskScenario(
+        task_id="fraud_signal_ambiguity",
+        title="Fraud Signal Ambiguity",
+        difficulty="medium",
+        objective="Choose whether to contest a CNP fraud dispute and curate only the evidence that helps.",
+        description=(
+            "A card-not-present fraud dispute with mixed signals. Strong account-linkage evidence exists, "
+            "but payment mismatch artifacts will hurt the case if attached."
+        ),
+        max_steps=12,
+        cases=(
+            InternalCase(
+                case_id="CB-M1",
+                order_id="ORD-8821",
+                customer_id="CUST-2048",
+                amount=480.0,
+                currency="USD",
+                reason_code="fraud_cnp",
+                summary="Issuer filed a card-not-present fraud dispute on a high-value electronics order.",
+                inspection_notes=(
+                    "The order used a known account and device, but AVS/CVV mismatches were present. "
+                    "Winning requires emphasizing customer-account linkage and avoiding mismatch artifacts."
+                ),
+                deadline_step=9,
+                optimal_strategy="contest",
+                acceptable_strategies=("accept_chargeback",),
+                policy_guidance=(
+                    "For CNP fraud disputes, contest only when you can link the cardholder to the account or device history. "
+                    "Do not attach evidence that strengthens the issuer's fraud narrative."
+                ),
+                policy_requirements=("prior good order linkage", "customer account confirmation"),
+                recommended_strategy="contest",
+                resolution_summary="Contest only with strong account-linkage evidence. Conceding is acceptable but suboptimal.",
+                weight=1.1,
+                required_evidence_ids=("M1-PRIOR-ORDERS", "M1-ACCOUNT-CHAT"),
+                helpful_evidence_ids=("M1-PRIOR-ORDERS", "M1-ACCOUNT-CHAT", "M1-DELIVERY"),
+                harmful_evidence_ids=("M1-AVS-MISMATCH", "M1-CVV-MISMATCH"),
+                evidence_by_system={
+                    "orders": (
+                        _ev(
+                            "M1-ORDER",
+                            "orders",
+                            "Order receipt",
+                            "Checkout receipt showing customer account id, shipping address, and same email as prior purchases.",
+                            helpful=True,
+                        ),
+                    ),
+                    "payment": (
+                        _ev(
+                            "M1-AVS-MISMATCH",
+                            "payment",
+                            "AVS mismatch detail",
+                            "Street-number mismatch was recorded at authorization time.",
+                            harmful=True,
+                        ),
+                        _ev(
+                            "M1-CVV-MISMATCH",
+                            "payment",
+                            "CVV mismatch detail",
+                            "CVV did not fully match at authorization time.",
+                            harmful=True,
+                        ),
+                        _ev(
+                            "M1-AUTH",
+                            "payment",
+                            "Authorization capture",
+                            "Payment was successfully authorized and captured.",
+                        ),
+                    ),
+                    "shipping": (
+                        _ev(
+                            "M1-DELIVERY",
+                            "shipping",
+                            "Carrier delivery confirmation",
+                            "Package was delivered to the saved customer address two days later.",
+                            helpful=True,
+                        ),
+                    ),
+                    "support": (
+                        _ev(
+                            "M1-ACCOUNT-CHAT",
+                            "support",
+                            "Authenticated support chat",
+                            "Customer logged into the account and confirmed the delivery window in chat before shipment.",
+                            helpful=True,
+                            required=True,
+                        ),
+                    ),
+                    "refunds": (
+                        _ev(
+                            "M1-NO-REFUND",
+                            "refunds",
+                            "Refund ledger",
+                            "No refund or cancellation was issued prior to the dispute.",
+                        ),
+                    ),
+                    "risk": (
+                        _ev(
+                            "M1-PRIOR-ORDERS",
+                            "risk",
+                            "Prior account activity",
+                            "Same account, same device fingerprint, and three prior fulfilled orders without disputes.",
+                            helpful=True,
+                            required=True,
+                        ),
+                        _ev(
+                            "M1-VELOCITY",
+                            "risk",
+                            "Velocity check",
+                            "No abnormal velocity or proxy usage detected.",
+                            helpful=True,
+                        ),
+                    ),
+                },
+            ),
+        ),
+    ),
+    "queue_optimization_hard": TaskScenario(
+        task_id="queue_optimization_hard",
+        title="Dispute Queue Optimization",
+        difficulty="hard",
+        objective="Maximize recovery across a queue of disputes while respecting deadlines and avoiding weak contests.",
+        description=(
+            "A real operations queue with three disputes. Two should be actioned quickly, and one should be conceded. "
+            "The step budget leaves little room for waste."
+        ),
+        max_steps=18,
+        cases=(
+            InternalCase(
+                case_id="CB-H1",
+                order_id="ORD-9901",
+                customer_id="CUST-4100",
+                amount=860.0,
+                currency="USD",
+                reason_code="goods_not_received",
+                summary="High-value furniture delivery disputed as not received.",
+                inspection_notes=(
+                    "Carrier stored both a delivery scan and signature. This is the highest-value recoverable case in the queue."
+                ),
+                deadline_step=7,
+                optimal_strategy="contest",
+                acceptable_strategies=(),
+                policy_guidance=(
+                    "Use merchant receipt plus carrier proof for goods-not-received disputes. This case is strong if contested on time."
+                ),
+                policy_requirements=("order confirmation", "signature-backed delivery proof"),
+                recommended_strategy="contest",
+                resolution_summary="Contest immediately with the signature-backed delivery packet.",
+                weight=1.7,
+                required_evidence_ids=("H1-ORDER-CONF", "H1-SIGNATURE"),
+                helpful_evidence_ids=("H1-ORDER-CONF", "H1-SIGNATURE", "H1-DELIVERY-SCAN"),
+                harmful_evidence_ids=(),
+                evidence_by_system={
+                    "orders": (
+                        _ev(
+                            "H1-ORDER-CONF",
+                            "orders",
+                            "Order invoice",
+                            "Signed furniture order invoice with billing and delivery address.",
+                            helpful=True,
+                            required=True,
+                        ),
+                    ),
+                    "payment": (
+                        _ev(
+                            "H1-AUTH",
+                            "payment",
+                            "Captured payment",
+                            "Payment authorization and capture both succeeded.",
+                        ),
+                    ),
+                    "shipping": (
+                        _ev(
+                            "H1-SIGNATURE",
+                            "shipping",
+                            "Delivery signature",
+                            "Carrier recorded a recipient signature at the shipping address.",
+                            helpful=True,
+                            required=True,
+                        ),
+                        _ev(
+                            "H1-DELIVERY-SCAN",
+                            "shipping",
+                            "Final-mile delivery scan",
+                            "Tracking confirms delivery within the promised window.",
+                            helpful=True,
+                        ),
+                    ),
+                    "support": (
+                        _ev(
+                            "H1-SUPPORT",
+                            "support",
+                            "Support history",
+                            "No delivery complaint was opened before the dispute.",
+                        ),
+                    ),
+                    "refunds": (
+                        _ev(
+                            "H1-NO-REFUND",
+                            "refunds",
+                            "Refund ledger",
+                            "No refund was issued.",
+                        ),
+                    ),
+                    "risk": (
+                        _ev(
+                            "H1-RISK",
+                            "risk",
+                            "Risk summary",
+                            "Low-risk order. No notable fraud flags.",
+                        ),
+                    ),
+                },
+            ),
+            InternalCase(
+                case_id="CB-H2",
+                order_id="ORD-9902",
+                customer_id="CUST-4101",
+                amount=240.0,
+                currency="USD",
+                reason_code="fraud_cnp",
+                summary="Apparel order disputed as unauthorized.",
+                inspection_notes=(
+                    "The account is new, there is no durable linkage to the cardholder, and the payment record contains mismatch artifacts. "
+                    "This case should be conceded."
+                ),
+                deadline_step=14,
+                optimal_strategy="accept_chargeback",
+                acceptable_strategies=("issue_refund",),
+                policy_guidance=(
+                    "Do not contest when you lack durable account or device linkage. Avoid wasting steps on weak fraud disputes."
+                ),
+                policy_requirements=("cardholder linkage evidence"),
+                recommended_strategy="accept_chargeback",
+                resolution_summary="Concede the dispute. Contesting wastes portfolio value.",
+                weight=0.8,
+                required_evidence_ids=(),
+                helpful_evidence_ids=(),
+                harmful_evidence_ids=("H2-AVS", "H2-CVV"),
+                evidence_by_system={
+                    "orders": (
+                        _ev(
+                            "H2-ORDER",
+                            "orders",
+                            "Order receipt",
+                            "Guest checkout with a new shipping address and no prior order history.",
+                        ),
+                    ),
+                    "payment": (
+                        _ev(
+                            "H2-AVS",
+                            "payment",
+                            "AVS mismatch detail",
+                            "Street and postal code mismatches were present.",
+                            harmful=True,
+                        ),
+                        _ev(
+                            "H2-CVV",
+                            "payment",
+                            "CVV mismatch detail",
+                            "CVV did not match.",
+                            harmful=True,
+                        ),
+                    ),
+                    "shipping": (
+                        _ev(
+                            "H2-DELIVERY",
+                            "shipping",
+                            "Carrier delivery confirmation",
+                            "Delivered to a new address without signature.",
+                        ),
+                    ),
+                    "support": (
+                        _ev(
+                            "H2-SUPPORT",
+                            "support",
+                            "Support log",
+                            "No authenticated support interactions were recorded.",
+                        ),
+                    ),
+                    "refunds": (
+                        _ev(
+                            "H2-NO-REFUND",
+                            "refunds",
+                            "Refund ledger",
+                            "No refund issued before the chargeback.",
+                        ),
+                    ),
+                    "risk": (
+                        _ev(
+                            "H2-RISK",
+                            "risk",
+                            "Risk summary",
+                            "Elevated risk score and no positive account history.",
+                        ),
+                    ),
+                },
+            ),
+            InternalCase(
+                case_id="CB-H3",
+                order_id="ORD-9903",
+                customer_id="CUST-4102",
+                amount=320.0,
+                currency="USD",
+                reason_code="credit_not_processed",
+                summary="Subscriber canceled before renewal and says the credit was never processed.",
+                inspection_notes=(
+                    "The merchant missed the promised refund SLA. This should be resolved fast with a refund, not a contest."
+                ),
+                deadline_step=4,
+                optimal_strategy="issue_refund",
+                acceptable_strategies=("accept_chargeback",),
+                policy_guidance=(
+                    "If the merchant failed to process a promised credit, refund immediately or concede. Contesting is not supportable."
+                ),
+                policy_requirements=("proof of cancellation request", "refund status check"),
+                recommended_strategy="issue_refund",
+                resolution_summary="Refund immediately. Delay turns a manageable loss into a deadline miss.",
+                weight=1.2,
+                required_evidence_ids=(),
+                helpful_evidence_ids=("H3-CANCEL", "H3-NO-REFUND"),
+                harmful_evidence_ids=(),
+                evidence_by_system={
+                    "orders": (
+                        _ev(
+                            "H3-ORDER",
+                            "orders",
+                            "Renewal invoice",
+                            "Subscription renewed automatically for the annual plan.",
+                        ),
+                    ),
+                    "payment": (
+                        _ev(
+                            "H3-PAYMENT",
+                            "payment",
+                            "Captured renewal payment",
+                            "Renewal payment settled successfully.",
+                        ),
+                    ),
+                    "shipping": (),
+                    "support": (
+                        _ev(
+                            "H3-CANCEL",
+                            "support",
+                            "Cancellation request",
+                            "Customer requested cancellation before renewal and support promised a refund within five business days.",
+                            helpful=True,
+                        ),
+                    ),
+                    "refunds": (
+                        _ev(
+                            "H3-NO-REFUND",
+                            "refunds",
+                            "Refund ledger",
+                            "No refund has been issued as of the dispute open date.",
+                            helpful=True,
+                        ),
+                    ),
+                    "risk": (),
+                },
+            ),
+        ),
+    ),
+}
+
+
+def get_task(task_id: str) -> TaskScenario:
+    """Look up a task or raise KeyError."""
+
+    return TASKS[task_id]
+
+
+def list_tasks() -> list[TaskScenario]:
+    """Return tasks in a stable order."""
+
+    ordered_ids = [
+        "goods_not_received_easy",
+        "fraud_signal_ambiguity",
+        "queue_optimization_hard",
+    ]
+    return [TASKS[task_id] for task_id in ordered_ids]