Response drift: hunch — `research.dataFreshness` absent from HunchRawResearch interface

[realfishsam]

Exchange

hunch

Severity

MEDIUM

What Our Normalizer Expects

The HunchRawResearch TypeScript interface does not declare a dataFreshness field. The hunch normalizer (normalizer.ts) does not access research.dataFreshness when processing research responses.

What The Live API Returns

The live /research endpoint returns a nested dataFreshness object on each research item:

research.dataFreshness.oddsAt: string      ← ISO timestamp when odds were last snapshotted
research.dataFreshness.snapshotAt: null
research.dataFreshness.observationsAt: null

Impact

• Consumers of the normalized hunch research data cannot detect stale odds — oddsAt is never surfaced
• The HunchRawResearch interface is incomplete; TypeScript gives no error if code tries to access raw.dataFreshness (it would just be undefined at runtime)
• Prediction accuracy metrics may silently use outdated odds without any staleness signal

Suggested Fix

1. Add dataFreshness to the HunchRawResearch interface:

   dataFreshness?: {
       oddsAt?: string;
       snapshotAt?: string | null;
       observationsAt?: string | null;
   };

2. In the normalizer, surface dataFreshness.oddsAt as a sourceMetadata field or a top-level timestamp on the normalized research output so consumers can detect and handle stale odds

---

Found by automated response shape drift audit

[realfishsam]

Closing as duplicate of #2126. Item 3 in #2126 already covers the same live-API field (dataFreshness on the hunch research endpoint, missing from the HunchRawResearch interface / api.ts) — the extra detail from this issue (exact nested shape, suggested interface snippet) has been copied over to #2126.

---

Generated by Claude Code