Normalize soft-failure error shape in Saturday Step Function

[cipher813]

Summary

Tonight's Saturday Step Function failure surfaced two bugs stacked. The first — alpha-engine-data writing "breadth": null into macro.json → research macro_agent crashing with AttributeError — was fixed in #13.

This PR fixes the second: when any Check* Choice state routed through its Default edge to HandleFailure, HandleFailure's Message template crashed the execution with:

States.Runtime: The JsonPath argument for the field '$.error'
could not be found in the input

Because $.error is only populated by the Catch blocks on Task failures — the Choice.Default path (soft failure, where a Lambda returned {"status": "ERROR"} or an SSM command ended non-Success) never sets it. Net effect:

1. The SNS alert never fired — the paged-on email relied on HandleFailure running successfully, and that state crashed before it could publish.
2. The execution died with a confusing States.Runtime meta-error instead of the real cause.
3. The real cause (the AttributeError in macro_agent) was buried under a JSONPath lookup failure, making tonight's triage take longer than it should have.

Fix

Insert a dedicated Pass extractor for each of the 5 Check* states. Each extractor copies the relevant poll object (or the Research Lambda Payload) into $.error under a shape that identifies which phase failed, then falls through to the existing HandleFailure. The Catch-based hard-failure path is unchanged — it still writes directly to $.error via ResultPath, so both paths converge on the same shape.

State machine grew from 25 → 30 states. The 5 new states:

Source Choice state	New extractor	Reads from
CheckDataPhase1Status.Default	ExtractDataPhase1Error	$.data_phase1_poll
CheckRAGStatus.Default	ExtractRAGError	$.rag_poll
CheckResearchStatus.Default	ExtractResearchError	$.research_result.Payload
CheckPredictorStatus.Default	ExtractPredictorError	$.predictor_poll
CheckBacktesterStatus.Default	ExtractBacktesterError	$.backtester_poll

Already applied to the live state machine

I ran `aws stepfunctions update-state-machine --definition file://infrastructure/step_function.json` before opening this PR so tonight's restart picks up the fix:

updateDate: 2026-04-10T18:00:23-07:00
revisionId: d836ff1d-1a8c-4cf7-b8dd-69a1262fad86

Verified via `describe-state-machine` that the live definition has 30 states, all 5 Extract* states present, and `CheckResearchStatus.Default` now points to `ExtractResearchError`. This commit keeps the repo source of truth aligned with the live definition.

Test plan

• JSON validates (`python3 -c "import json; json.load(open(...))"`)
• All 5 Check*.Default targets verified against expected Extract* names
• Every Extract* state has `Type=Pass`, `Next=HandleFailure`, `ResultPath=$.error`
• `HandleFailure` Message template unchanged
• Live SM update succeeded
• End-to-end test: restart tonight's failed Saturday execution and confirm (a) Research runs green now that Fix macro breadth: compute from slim cache instead of writing null #13 is deployed, or (b) if something else soft-fails, HandleFailure fires SNS instead of `States.Runtime`

Out of scope

• Fix the defensive fallback in `alpha-engine-research/agents/macro_agent.py:176` (breadth None-safety safety net). Latent now that Fix macro breadth: compute from slim cache instead of writing null #13 is on main.
• Investigate the 3× `NoSuchKey` retries in research Lambda logs (noise, but something is hammering a missing S3 key).

🤖 Generated with Claude Code