feat: seed-variant pool + chain gate enforcement

- tasks.py: add TASK_VARIANTS with 2 alternative scenarios per task for 14
tasks (MED-003..006, HARD-001..006, CRIT-001..004); each variant has a
different correct_action discoverable only via investigation reveals;
pre-investigation observation is genuinely ambiguous - closes the
correct_action memorisation exploit
- environment.py: replace fragile threshold-based variant system with clean
seed-deterministic variant pool selection;
(seed * 1009 + task_idx * 17) % (n+1) gives good distribution across seeds;
seed=0 always uses base variants (all existing tests remain stable)
- environment.py: add multi-step chain gate to step_async - CRIT tasks with
chain_total > 1 require (chain_total - 1) investigation steps before a
terminal decision is accepted; blocked attempts return chain_gate_blocked
event with chain_steps_needed indicator and -0.05 reward signal

environment.py

@@ -24,7 +24,7 @@ from typing import Deque, List, Optional
 
 from payops_env.grader import INVESTIGATION_BONUS, grade
 from payops_env.models import PayOpsAction, PayOpsObservation, PayOpsState
-from payops_env.tasks import ACTION_COSTS, TASKS, PayOpsTask
+from payops_env.tasks import ACTION_COSTS, TASK_VARIANTS, TASKS, PayOpsTask
 
 
 TERMINAL_ACTIONS   = {"approve", "reject", "flag", "escalate", "hold"}
@@ -84,79 +84,27 @@ class PayOpsEnvironment:
                 jt.velocity_24h = max(0, t.velocity_24h + rng.randint(-3, 3))
             jittered.append(jt)
         self._tasks = jittered
-        # Apply jitter variants: for borderline tasks the correct_action can change
-        # based on jittered values, preventing memorisation of fixed correct answers.
-        # Variants cover 10 of 20 tasks for broad anti-memorisation coverage.
-        for jt in self._tasks:
-            if jt.task_id == "EASY-004":
-                # Base velocity_1h=15 (jittered 12–18).
-                # >= 17: card-clone severity warrants immediate escalation.
-                if (jt.velocity_1h or 0) >= 17:
-                    jt.correct_action = "escalate"
-                    jt.partial_credit_actions = {"flag": 0.5, "hold": 0.4}
-
-            elif jt.task_id == "MED-001":
-                # Base risk_score=0.52, amount=85k (cross-border B2B).
-                # Low jitter: if risk drops below 0.48 AND amount stays modest → approve.
-                if jt.risk_score < 0.48 and jt.amount < 90_000:
-                    jt.correct_action = "approve"
-                    jt.partial_credit_actions = {"escalate": 0.5, "flag": 0.3}
-
-            elif jt.task_id == "MED-003":
-                # Base amount≈450 (jittered 382–540).
-                # >= 500: spike is large enough to hold rather than flag.
-                if jt.amount >= 500.0:
-                    jt.correct_action = "hold"
-                    jt.partial_credit_actions = {"flag": 0.5, "escalate": 0.3}
-
-            elif jt.task_id == "MED-004":
-                # Base risk_score=0.58 (jittered ±0.03).
-                # >= 0.62: risk crosses the senior-review threshold → escalate.
-                if jt.risk_score >= 0.62:
-                    jt.correct_action = "escalate"
-                    jt.partial_credit_actions = {"flag": 0.5, "hold": 0.3}
-
-            elif jt.task_id == "MED-006":
-                # Base risk_score=0.56, amount=120k real-estate advance.
-                # Low jitter: if risk drops below 0.50 and amount < 110k → hold not escalate.
-                if jt.risk_score < 0.50 and jt.amount < 110_000:
-                    jt.correct_action = "hold"
-                    jt.partial_credit_actions = {"flag": 0.4, "escalate": 0.5}
-
-            elif jt.task_id == "HARD-001":
-                # Base risk_score=0.18 (poisoned), counterparty=watchlist.
-                # If velocity_1h jitters up to >= 3: pattern is undeniable → reject not escalate.
-                if (jt.velocity_1h or 0) >= 3:
-                    jt.correct_action = "reject"
-                    jt.partial_credit_actions = {"escalate": 0.5, "flag": 0.4, "hold": 0.3}
-
-            elif jt.task_id == "HARD-006":
-                # Base amount=3200 EUR, risk=0.63 (ghost account / mule reactivation).
-                # High spike: if amount >= 3700 → escalate urgently, not just flag.
-                if jt.amount >= 3_700:
-                    jt.correct_action = "escalate"
-                    jt.partial_credit_actions = {"flag": 0.5, "hold": 0.4}
-
-            elif jt.task_id == "CRIT-001":
-                # Base risk_score=0.59 (PE wire, legit).
-                # If risk jitters above 0.80 → escalate for extra scrutiny before approve.
-                if jt.risk_score >= 0.80:
-                    jt.correct_action = "escalate"
-                    jt.partial_credit_actions = {"flag": 0.4, "hold": 0.35, "approve": 0.3}
-
-            elif jt.task_id == "CRIT-003":
-                # Base amount=680k trade-based ML (escalate).
-                # If amount jitters very high (>= 780k) → reject outright; over-invoicing extreme.
-                if jt.amount >= 780_000:
-                    jt.correct_action = "reject"
-                    jt.partial_credit_actions = {"escalate": 0.5, "flag": 0.3}
-
-            elif jt.task_id == "CRIT-004":
-                # Base risk=0.81, geo-impossible ATO (reject).
-                # If risk jitters below 0.75 → hold pending contact_sender confirmation.
-                if jt.risk_score < 0.75:
-                    jt.correct_action = "hold"
-                    jt.partial_credit_actions = {"escalate": 0.5, "reject": 0.4}
+
+        # ── Variant pool selection ──────────────────────────────────────────────
+        # Each task in TASK_VARIANTS has 2 alternative scenarios (in addition to
+        # the base).  The episode seed selects which scenario plays out, making
+        # the correct_action unknowable from the task_id alone — the agent MUST
+        # investigate to discover the decisive evidence.
+        #
+        # seed=0 is the canonical episode (all base variants); used by the test
+        # suite so that hardcoded expected rewards remain stable.
+        if episode_seed != 0:
+            for i, jt in enumerate(self._tasks):
+                variants = TASK_VARIANTS.get(jt.task_id, [])
+                if not variants:
+                    continue
+                # variant_idx=0 → base (no changes); 1..N → variants[0..N-1]
+                variant_idx = (episode_seed * 1009 + i * 17) % (len(variants) + 1)
+                if variant_idx == 0:
+                    continue
+                overrides = variants[variant_idx - 1]
+                for key, val in overrides.items():
+                    setattr(jt, key, val)
         self._current_task = self._tasks[0]
         self._used_inv = {}
         self._sar_filed = set()
@@ -197,6 +145,30 @@ class PayOpsEnvironment:
         task_id = task.task_id
         cost = ACTION_COSTS.get(action_type, 0.0)
 
+        # ── MULTI-STEP CHAIN GATE ─────────────────────────────────────────────
+        # Critical tasks with chain_total > 1 require (chain_total − 1)
+        # investigation sub-actions before a terminal decision is accepted.
+        # Blocked attempts return a helpful message without advancing the task.
+        if action_type in TERMINAL_ACTIONS:
+            chain_min = max(0, getattr(task, "chain_total", 1) - 1)
+            inv_done  = len(self._used_inv.get(task_id, set()))
+            if chain_min > 0 and inv_done < chain_min:
+                needed = chain_min - inv_done
+                return self._make_observation(
+                    reward=-0.05,
+                    done=False,
+                    info={
+                        "event":              "chain_gate_blocked",
+                        "chain_status":       "investigation_required",
+                        "chain_steps_needed": needed,
+                        "message": (
+                            f"This {task.difficulty} transaction requires {needed} "
+                            f"more investigation step(s) before a terminal decision. "
+                            f"Please investigate first."
+                        ),
+                    },
+                )
+
         # Deduct cost
         self._state.budget_spent = round(self._state.budget_spent + cost, 4)
         self._state.step_count   += 1

tasks.py

@@ -701,4 +701,407 @@ ACTION_COSTS: Dict[str, float] = {
     "file_sar": 0.05,   # intentionally cheap — incentivise regulatory compliance
 }
 
+# ---------------------------------------------------------------------------
+# Task variant pools — anti-memorisation & investigation-gating
+# ---------------------------------------------------------------------------
+# Each entry is a list of override dicts for alternative scenarios of that task.
+# Variant index 0 always means "use base task" (no overrides applied).
+# Variants 1..N override the fields listed, so the correct_action is only
+# determinable after performing the required investigation sub-actions.
+# The variant is selected deterministically from the episode seed in environment.py.
+#
+# Key design constraint: the BASE observation (pre-investigation) must be
+# genuinely ambiguous — investigation reveals ARE the decisive evidence.
+# ---------------------------------------------------------------------------
+TASK_VARIANTS: Dict[str, List[Dict]] = {
+
+    # ── MEDIUM ────────────────────────────────────────────────────────────
+
+    "MED-003": [
+        # v1: unauthorised recurring billing → hold to freeze
+        {
+            "correct_action": "hold",
+            "partial_credit_actions": {"flag": 0.5, "escalate": 0.3},
+            "inspect_reveal": (
+                "Merchant billing records show 3 prior declined charges this month "
+                "from different cards linked to the same subscriber IP. Pattern is "
+                "consistent with credential stuffing / unauthorised recurring charge. "
+                "Freeze payment and contact customer before releasing."
+            ),
+        },
+        # v2: confirmed annual plan upgrade → approve
+        {
+            "correct_action": "approve",
+            "partial_credit_actions": {"flag": 0.3},
+            "inspect_reveal": (
+                "Customer service log: subscriber upgraded to annual plan via phone "
+                "this morning. $449.97 = 3 × monthly fee (annual discount applied). "
+                "Merchant has confirmed the charge. Safe to approve."
+            ),
+        },
+    ],
+
+    "MED-004": [
+        # v1: structuring pattern across exchanges → escalate
+        {
+            "correct_action": "escalate",
+            "partial_credit_actions": {"flag": 0.5, "hold": 0.3},
+            "inspect_reveal": (
+                "Sender has made 7 crypto exchange payments in 5 days totalling $28k "
+                "across 3 different platforms. Amounts stay just below exchange reporting "
+                "limits. Pattern matches structuring. Escalate for AML review."
+            ),
+        },
+        # v2: clean recurring investment → approve
+        {
+            "correct_action": "approve",
+            "partial_credit_actions": {"flag": 0.3},
+            "inspect_reveal": (
+                "Sender's 3-year payment history shows consistent quarterly crypto "
+                "purchases of similar size. Exchange is fully regulated and KYC-verified. "
+                "Amount within personal investment limits. No structuring indicators. Approve."
+            ),
+        },
+    ],
+
+    "MED-005": [
+        # v1: KYC discrepancy found → escalate
+        {
+            "correct_action": "escalate",
+            "partial_credit_actions": {"flag": 0.5, "hold": 0.3},
+            "kyc_reveal": (
+                "KYC expired because the compliance team found discrepancies between "
+                "the business registration address and Companies House records. The "
+                "case has been flagged for investigation by the KYC team. Escalate — "
+                "do not approve or hold without senior sign-off."
+            ),
+        },
+        # v2: KYC renewed, routine payroll → approve
+        {
+            "correct_action": "approve",
+            "partial_credit_actions": {"hold": 0.4},
+            "kyc_reveal": (
+                "KYC renewal was submitted 10 days ago and completed processing "
+                "yesterday. All checks passed. The lapse was an administrative "
+                "oversight only. Payroll has an 18-month history with no anomalies. "
+                "Approve and process."
+            ),
+        },
+    ],
+
+    "MED-006": [
+        # v1: forged purchase agreement → reject
+        {
+            "correct_action": "reject",
+            "partial_credit_actions": {"escalate": 0.4, "flag": 0.3},
+            "docs_reveal": (
+                "Purchase agreement is a forgery: the notary seal serial number "
+                "does not exist in the notary registry; the property title number "
+                "returns no match in Land Registry; the 'escrow agent' is not "
+                "registered with the Council for Licensed Conveyancers. "
+                "Classic conveyancing fraud — reject immediately."
+            ),
+        },
+        # v2: title dispute — hold pending resolution
+        {
+            "correct_action": "hold",
+            "partial_credit_actions": {"escalate": 0.5, "flag": 0.3},
+            "docs_reveal": (
+                "SPA is authentic and escrow agent is licensed. However, a co-owner "
+                "has filed a title dispute on the property. The buyer's solicitor "
+                "advises funds should be held in escrow until the dispute is resolved "
+                "(expected 3–4 weeks). Hold pending legal clearance."
+            ),
+        },
+    ],
+
+    # ── HARD ──────────────────────────────────────────────────────────────
+
+    "HARD-001": [
+        # v1: deeper forensics confirm active fraud ring → reject
+        {
+            "correct_action": "reject",
+            "partial_credit_actions": {"escalate": 0.5, "flag": 0.3},
+            "inspect_reveal": (
+                "Cross-database query: same receiver account (payee@solicitor-uk.com) "
+                "appeared in 4 prior rejected fraud wires this quarter, total £190k. "
+                "Funds clear to offshore within 45 min each time. ML score was "
+                "deliberately poisoned via clean-account seeding. Reject immediately."
+            ),
+        },
+        # v2: flags are false positives, ML score correct → approve
+        {
+            "correct_action": "approve",
+            "partial_credit_actions": {"escalate": 0.4, "flag": 0.3},
+            "inspect_reveal": (
+                "Manual flag investigation: 'solicitor_mule_pattern' rule mis-fired "
+                "on a legitimate SRA-registered firm (reg. SRA-443210) that rebranded "
+                "last month, causing a new account. 'New_account_7d' flag triggered "
+                "by the rebrand. ALL flags are false positives. ML risk score 0.18 is "
+                "accurate. Safe to approve."
+            ),
+        },
+    ],
+
+    "HARD-002": [
+        # v1: new legitimate supplier, flags were incorrect → approve
+        {
+            "correct_action": "approve",
+            "partial_credit_actions": {"flag": 0.4, "hold": 0.3},
+            "contact_reveal": (
+                "Sender confirmed: mule_relay_2287@fastpay.io is their new supplier "
+                "in Singapore. The VPN flagged by geo-risk monitoring is the company's "
+                "standard corporate security policy. Purchase order #PO-44821 is on "
+                "file matching the amount. Safe to approve."
+            ),
+        },
+        # v2: inconsistent story, AML review needed → escalate
+        {
+            "correct_action": "escalate",
+            "partial_credit_actions": {"reject": 0.4, "flag": 0.3},
+            "contact_reveal": (
+                "Contacted sender: story is vague and inconsistent across two "
+                "follow-up calls. Cannot confirm supplier identity. No purchase order "
+                "provided. The receiver's business registration cannot be located. "
+                "Cannot approve or reject — escalate to AML for investigation."
+            ),
+        },
+    ],
+
+    "HARD-003": [
+        # v1: confirmed structuring but scale needs MLRO → escalate
+        {
+            "correct_action": "escalate",
+            "partial_credit_actions": {"reject": 0.5, "flag": 0.3},
+            "inspect_reveal": (
+                "Pattern strongly resembles CTR structuring. However, the total "
+                "aggregate ($27,750) and the involvement of 3 related entities "
+                "means this crosses the threshold for mandatory MLRO referral under "
+                "internal policy. Escalate rather than unilaterally reject."
+            ),
+        },
+        # v2: same UBO transfers are authorised corporate restructuring → hold
+        {
+            "correct_action": "hold",
+            "partial_credit_actions": {"reject": 0.4, "escalate": 0.5},
+            "inspect_reveal": (
+                "Same-UBO transfers are documented in a board resolution dated last "
+                "week authorising an internal corporate restructuring. KYC failure "
+                "was due to an ID document resubmission still in queue. Structuring "
+                "indicators are coincidental. Hold pending KYC re-verification."
+            ),
+        },
+    ],
+
+    "HARD-004": [
+        # v1: unrecognised SWIFT BIC, potential impersonation → reject
+        {
+            "correct_action": "reject",
+            "partial_credit_actions": {"escalate": 0.5, "flag": 0.3},
+            "inspect_reveal": (
+                "SWIFT BIC vostro@bank-b-swift.com resolved to a bank that does NOT "
+                "appear in the correspondent banking agreement registry. The BIC is "
+                "visually similar to a legitimate bank (one character substituted). "
+                "Likely impersonation of a correspondent partner — reject and alert."
+            ),
+        },
+        # v2: ghost employees detected → flag for payroll audit
+        {
+            "correct_action": "flag",
+            "partial_credit_actions": {"approve": 0.5, "hold": 0.4},
+            "inspect_reveal": (
+                "FX settlement accounts are SWIFT-verified and legitimate. However, "
+                "the initiating staff workflow shows this $4.2M wire was split from "
+                "a larger batch that included 2 non-existent internal accounts. "
+                "Flag for payroll/treasury audit before releasing."
+            ),
+        },
+    ],
+
+    "HARD-005": [
+        # v1: confirmed insider fraud, no response from staff → reject
+        {
+            "correct_action": "reject",
+            "partial_credit_actions": {"escalate": 0.5, "flag": 0.3},
+            "contact_reveal": (
+                "Staff member's phone is disconnected; email bounced. HR confirms "
+                "the employee was placed on garden leave 2 days ago pending "
+                "investigation. Receiver account drained offshore within hours of "
+                "prior similar payments. Insider fraud confirmed — reject and freeze."
+            ),
+        },
+        # v2: authorized vendor payment, staff working late → approve
+        {
+            "correct_action": "approve",
+            "partial_credit_actions": {"escalate": 0.4, "flag": 0.3},
+            "contact_reveal": (
+                "Staff member confirmed: personal Gmail was added as a forwarding "
+                "alias last month when the vendor switched to a personal invoicing "
+                "service. Contract reference VC-2024-189 verified by procurement. "
+                "After-hours initiation matches remote work schedule. Approve."
+            ),
+        },
+    ],
+
+    "HARD-006": [
+        # v1: confirmed active mule network → reject
+        {
+            "correct_action": "reject",
+            "partial_credit_actions": {"escalate": 0.5, "flag": 0.4},
+            "inspect_reveal": (
+                "Receiver account confirmed to be receiving from 12 other dormant "
+                "accounts this week (total €78k). All funds exit to the same offshore "
+                "cluster within 2 hours. Active money-mule aggregation network. "
+                "Reject and file SAR immediately."
+            ),
+        },
+        # v2: estate probate settlement, legitimate size → escalate
+        {
+            "correct_action": "escalate",
+            "partial_credit_actions": {"flag": 0.6, "hold": 0.4},
+            "inspect_reveal": (
+                "Account was frozen under a probate order that was lifted 3 days ago. "
+                "Estate settlement documentation is on file. Amount (€3,200) is "
+                "consistent with a partial distribution from the estate. Legitimate "
+                "reactivation — escalate for senior approval given the reactivation flag."
+            ),
+        },
+    ],
+
+    # ── CRITICAL ──────────────────────────────────────────────────────────
+
+    "CRIT-001": [
+        # v1: deepfake deal, BEC fraud → reject
+        {
+            "correct_action": "reject",
+            "partial_credit_actions": {"escalate": 0.4, "hold": 0.35, "flag": 0.3},
+            "inspect_reveal": (
+                "PE firm name verified but domain is a typo-squatting lookalike "
+                "(pe-flrm.com vs pe-firm.com). No SEC filing exists for this deal. "
+                "The 'press announcement' URL leads to a page created 6 days ago. "
+                "Classic BEC / CEO impersonation fraud."
+            ),
+            "docs_reveal": (
+                "'Signed SPA' is a doctored template — notarization certificate "
+                "serial number LN-2024-00512 does not exist in the notary registry. "
+                "Acquisition is fabricated. Reject and alert security team."
+            ),
+        },
+        # v2: legitimate deal, wrong destination account → hold
+        {
+            "correct_action": "hold",
+            "partial_credit_actions": {"approve": 0.4, "escalate": 0.5},
+            "inspect_reveal": (
+                "PE firm and deal confirmed as genuine (SEC filing #0001234567). "
+                "Press announcement verified with three external sources. Acquisition "
+                "is legitimate. However, the destination account does not match the "
+                "independent escrow account specified in clause 7.3 of the SPA."
+            ),
+            "docs_reveal": (
+                "SPA authenticated by legal team. Per clause 7.3, all milestone "
+                "payments must route to independent escrow account "
+                "escrow@trustco-escrow.com, not directly to the acquisition target. "
+                "Hold and redirect to the correct escrow account."
+            ),
+        },
+    ],
+
+    "CRIT-002": [
+        # v1: same SME, multiple business accounts — coincidental threshold → hold
+        {
+            "correct_action": "hold",
+            "partial_credit_actions": {"reject": 0.5, "escalate": 0.4},
+            "inspect_reveal": (
+                "The 3 flagged accounts all belong to the same registered SME "
+                "(Companies House reg. 09876543) using separate business accounts "
+                "for different cost centres. The $4,900 pattern matches their "
+                "internal expense approval limit — not structuring intent. "
+                "KYC re-verification recommended before releasing. Hold."
+            ),
+        },
+        # v2: ring is larger (9 accounts), MLRO escalation needed → escalate
+        {
+            "correct_action": "escalate",
+            "partial_credit_actions": {"reject": 0.5, "flag": 0.3},
+            "inspect_reveal": (
+                "Network analysis reveals the ring involves 9 accounts total (not 3), "
+                "all created on the same day, all funnelling to the same offshore "
+                "collector. Aggregate total is $42k. Volume and complexity require "
+                "MLRO involvement and a formal SAR — escalate rather than unilaterally reject."
+            ),
+        },
+    ],
+
+    "CRIT-003": [
+        # v1: legitimate specialized goods, market price correct → approve
+        {
+            "correct_action": "approve",
+            "partial_credit_actions": {"escalate": 0.5, "hold": 0.3},
+            "docs_reveal": (
+                "Independent commodity valuation confirms: these are custom precision "
+                "industrial components for semiconductor manufacturing. Verified market "
+                "price: $1,310–1,420 per unit. Invoice price of $1,360 is within "
+                "normal range. No mismatch. Documentation is clean."
+            ),
+            "inspect_reveal": (
+                "Full shipping manifest verified: 500 units dispatched per bill of "
+                "lading BoL-HK-2024-8821. Customs clearance certified in both "
+                "Hong Kong and the destination country. No discrepancies."
+            ),
+        },
+        # v2: criminal-scale TBML, reject immediately
+        {
+            "correct_action": "reject",
+            "partial_credit_actions": {"escalate": 0.5, "flag": 0.3},
+            "docs_reveal": (
+                "Invoice declares 500 units @ $1,360 = $680k. Independent valuation: "
+                "market price is $250/unit. Over-invoiced by 5.4×. Matches a "
+                "trade-based money laundering typology filed with FATF last year. "
+                "Criminal-level TBML — reject and file SAR immediately."
+            ),
+            "inspect_reveal": (
+                "Shipping records show only 100 units dispatched vs 500 invoiced. "
+                "Invoice-to-goods ratio 5.4× above market. Direct evidence of false "
+                "customs declarations. Reject immediately."
+            ),
+        },
+    ],
+
+    "CRIT-004": [
+        # v1: CEO delegated to CFO who was in Lagos — hold for confirmation
+        {
+            "correct_action": "hold",
+            "partial_credit_actions": {"escalate": 0.5, "reject": 0.4},
+            "inspect_reveal": (
+                "Geo-impossible login flagged. However, a delegation email from the "
+                "CEO was sent 2 hours ago via their verified corporate account granting "
+                "the CFO emergency signing authority for this exact transfer. "
+                "CFO was in Lagos for a board meeting (flight records available). "
+            ),
+            "contact_reveal": (
+                "CEO confirmed via secure callback: CFO had full authority to initiate "
+                "this transfer. Delegation is documented in the board minutes. "
+                "Hold briefly to verify the papertrail, then release."
+            ),
+        },
+        # v2: CEO unreachable, dual-approval controls met, escalate
+        {
+            "correct_action": "escalate",
+            "partial_credit_actions": {"reject": 0.5, "hold": 0.4},
+            "inspect_reveal": (
+                "Account takeover strongly suspected. CEO's registered number is "
+                "unreachable (OOO message). However, the transfer went through the "
+                "standard dual-approval workflow with two internal approvers (both "
+                "records look genuine). Outcome ambiguous — escalate to Fraud "
+                "Operations for emergency investigation."
+            ),
+            "contact_reveal": (
+                "Cannot reach CEO. Deputy CFO states they approved the transfer but "
+                "cannot confirm whether the CEO or an impersonator initiated it. "
+                "Escalate immediately to Fraud Ops and place a temporary hold."
+            ),
+        },
+    ],
+}
+