fix(futures): stop 422 on NO_TRADE plans, harden expires_at parsing

Root cause: trade_cycle._empty_plan() (used for every NO_TRADE / rejected
analysis) set expires_at=None, while plans_repo.validate_plan() requires
a parseable expires_at on every persisted plan -- including NO_TRADE ones,
checked before the NO_TRADE early return. Every rejected analysis therefore
failed plan persistence with 422 "Trade plan validation failed" /
PlanValidationError("expires_at must be a valid UTC timestamp").

- trade_cycle.py: _empty_plan() now sets expires_at to a real, short-lived
UTC expiry (created_at + NO_TRADE_PLAN_TTL_SECONDS, new independently
configurable env var, defaults to the existing PLAN_MAX_AGE_SECONDS).
decision stays NO_TRADE and executable stays False, so this plan can
never be traded regardless of expiry -- the timestamp only exists to
satisfy the domain schema.
- plans_repo.py: _epoch() now accepts general ISO-8601 (fractional
seconds, explicit UTC/non-UTC offsets) in addition to the canonical
"%Y-%m-%dT%H:%M:%SZ" fast path, and normalizes naive/non-UTC input to
UTC before comparison. Still rejects genuinely invalid/missing input.
- tests: new hermes_overlay/tests/test_expires_at_normalization.py
reproduces the original 422 (NO_TRADE plan with expires_at=None) and
asserts it's fixed, plus covers the ISO-8601 variants and malformed
input.

Verified: full test suite run locally, 425 passed (2 pre-existing,
unrelated failures around Dockerfile/dependency-inventory pinning left
untouched).

hermes_overlay/tests/test_expires_at_normalization.py

@@ -0,0 +1,88 @@
+"""Regression test for the /api/futures/analyze 422:
+
+    "Trade plan validation failed" -> PlanValidationError:
+    "expires_at must be a valid UTC timestamp"
+
+Root cause: trade_cycle._empty_plan() (used for every NO_TRADE / rejected
+analysis) set expires_at=None, while plans_repo.validate_plan() requires
+expires_at on every persisted plan -- including NO_TRADE ones -- before its
+NO_TRADE early return. Any rejected analysis therefore failed plan
+persistence with a 422.
+"""
+from __future__ import annotations
+
+import time
+
+import pytest
+
+from trading.domain.plans_repo import PlanValidationError, validate_plan
+from trading.trade_cycle import _empty_plan, _iso
+
+
+def _base_no_trade_plan(**overrides):
+    plan = _empty_plan(
+        symbol="BTCUSDT",
+        decision="NO_TRADE",
+        reasons=["Order book unavailable"],
+        warnings=[],
+        components={},
+        external_context={},
+        created_at=time.time(),
+        risk_profile="moderate",
+    )
+    # _empty_plan() doesn't set the market-context fields that
+    # _attach_context_metadata() normally adds; fill in the rest of
+    # REQUIRED_PLAN_FIELDS so we're testing expires_at in isolation.
+    plan.setdefault("futuresVerified", False)
+    plan.setdefault("trading_readiness", "blocked")
+    plan.update(overrides)
+    return plan
+def test_no_trade_plan_no_longer_ships_expires_at_none():
+    """This is the exact shape that used to 422 in production."""
+    plan = _base_no_trade_plan()
+    assert plan["expires_at"] is not None
+    validate_plan(plan)  # must not raise
+
+
+def test_no_trade_plan_expiry_is_canonical_utc_and_after_creation():
+    plan = _base_no_trade_plan()
+    assert plan["expires_at"].endswith("Z")
+    parsed = time.strptime(plan["expires_at"], "%Y-%m-%dT%H:%M:%SZ")
+    created = time.strptime(plan["created_at"], "%Y-%m-%dT%H:%M:%SZ")
+    assert parsed >= created
+
+
+@pytest.mark.parametrize(
+    "expires_at",
+    [
+        None,
+        "",
+        "not-a-timestamp",
+        "2026-13-40T99:99:99Z",
+    ],
+)
+def test_missing_or_malformed_expires_at_still_rejected(expires_at):
+    """The fix must not silently accept genuinely invalid input."""
+    plan = _base_no_trade_plan(expires_at=expires_at)
+    with pytest.raises(PlanValidationError, match="expires_at"):
+        validate_plan(plan)
+
+
+@pytest.mark.parametrize(
+    "expires_at",
+    [
+        "2099-01-01T00:00:00Z",           # canonical form this service emits
+        "2099-01-01T00:00:00+00:00",      # explicit UTC offset
+        "2099-01-01T00:00:00.123456Z",    # fractional seconds
+        "2099-01-01T05:30:00+05:30",      # non-UTC offset, must normalize
+        "2099-01-01T00:00:00",            # naive -- treated as UTC
+    ],
+)
+def test_general_iso8601_variants_are_accepted(expires_at):
+    plan = _base_no_trade_plan(expires_at=expires_at)
+    validate_plan(plan)  # must not raise for any of these
+
+
+def test_iso_helper_output_matches_required_canonical_format():
+    ts = _iso(1900000000.0)
+    assert ts == "2030-03-17T17:46:40Z"

hermes_overlay/trading/domain/plans_repo.py

@@ -11,6 +11,7 @@ import json
 import math
 import time
 import uuid
+from datetime import datetime, timezone
 from typing import Any, Dict, Optional
 
 from trading.domain.schema import connect
@@ -43,16 +44,40 @@ REQUIRED_PLAN_FIELDS = {
 
 
 def _epoch(value: Any) -> Optional[float]:
+    """Parse expires_at into a UTC epoch, or None if it isn't a valid timestamp.
+
+    Accepts:
+      - a numeric epoch (int/float), returned as-is
+      - the canonical "%Y-%m-%dT%H:%M:%SZ" string this service emits (fast path)
+      - general ISO-8601 strings, including fractional seconds and explicit
+        offsets ("...+05:30", "...Z")
+      - naive ISO-8601 strings with no offset, treated as UTC (this service
+        never stores local time)
+    All non-UTC offsets are converted to UTC before conversion to epoch.
+    """
     if value is None:
         return None
     if isinstance(value, (int, float)):
         number = float(value)
         return number if math.isfinite(number) else None
     if isinstance(value, str):
+        text = value.strip()
+        if not text:
+            return None
         try:
-            return float(calendar.timegm(time.strptime(value, "%Y-%m-%dT%H:%M:%SZ")))
+            return float(calendar.timegm(time.strptime(text, "%Y-%m-%dT%H:%M:%SZ")))
         except (TypeError, ValueError, OverflowError):
+            pass
+        iso_text = text[:-1] + "+00:00" if text.endswith("Z") else text
+        try:
+            parsed = datetime.fromisoformat(iso_text)
+        except ValueError:
             return None
+        if parsed.tzinfo is None:
+            parsed = parsed.replace(tzinfo=timezone.utc)
+        else:
+            parsed = parsed.astimezone(timezone.utc)
+        return parsed.timestamp()
     return None
 
 

hermes_overlay/trading/trade_cycle.py

@@ -50,6 +50,13 @@ STOP_ATR_MULTIPLIER = float(os.environ.get("FUTURES_STOP_ATR_MULTIPLIER", "1.2")
 TAKE_PROFIT_RR = float(os.environ.get("FUTURES_TAKE_PROFIT_RR", "1.8"))
 MIN_STOP_BPS = float(os.environ.get("FUTURES_MIN_STOP_BPS", "20"))  # basis points of entry
 PLAN_MAX_AGE_SECONDS = float(os.environ.get("FUTURES_PLAN_MAX_AGE_SECONDS", "20"))
+# Validity window for NO_TRADE / rejected-analysis records. These plans are
+# never executable (decision stays NO_TRADE, executable stays False), but the
+# domain layer's plan schema (trading.domain.plans_repo.validate_plan)
+# requires every persisted plan -- including rejected ones -- to carry a
+# parseable expires_at. Independently configurable from the directional plan
+# TTL above so the two can be tuned separately.
+NO_TRADE_PLAN_TTL_SECONDS = float(os.environ.get("FUTURES_NO_TRADE_PLAN_TTL_SECONDS", str(PLAN_MAX_AGE_SECONDS)))
 DEFAULT_REQUESTED_LEVERAGE = int(os.environ.get("FUTURES_DEFAULT_LEVERAGE", "5"))
 
 HIGH_ATR_PCT_PENALTY_THRESHOLD = 0.03  # matches risk.py's own high-vol threshold
@@ -291,7 +298,14 @@ def _empty_plan(symbol: str, decision: str, reasons: list, warnings: list,
                  risk_profile: str, *, no_trade_guard: bool = False,
                  external_advisory: Optional[dict] = None,
                  score: Optional[float] = None) -> dict:
-    """Return a completed, non-executable analysis record with no fake expiry."""
+    """Return a completed, non-executable analysis record.
+
+    decision stays "NO_TRADE" and executable stays False, so this record can
+    never be traded regardless of its expiry -- but the domain layer's plan
+    schema still requires every persisted plan to carry a parseable
+    expires_at, so we give it a real (short) validity window rather than
+    None. See NO_TRADE_PLAN_TTL_SECONDS above.
+    """
     return {
         "symbol": symbol, "decision": decision, "score": score,
         "confidence": abs(score) if score is not None else None,
@@ -303,7 +317,8 @@ def _empty_plan(symbol: str, decision: str, reasons: list, warnings: list,
         "external_advisory": external_advisory, "noTradeGuard": bool(no_trade_guard),
         "plan_type": "rejected_analysis", "executable": False, "analysis_state": "NO_TRADE",
         "executed": False, "execution_result": None,
-        "created_at": _iso(created_at), "expires_at": None,
+        "created_at": _iso(created_at),
+        "expires_at": _iso(created_at + NO_TRADE_PLAN_TTL_SECONDS),
     }