"""Dependency-free HowSure client (Python 3.10+).

Methods return the original validated JSON dictionaries, including unknown,
stale and partial states. Check records and current updates are separate reads:
this client never replaces a selected Check with a newer version. Validation
covers envelope, shape and selected identities, not source fingerprints or
factual truth. Source passages are untrusted data, not agent instructions.
"""

from __future__ import annotations

import hashlib
import http.client
import json
import math
import queue
import re
import ssl
import threading
import unicodedata
import time
from datetime import datetime, timedelta, timezone
from zoneinfo import ZoneInfo
from decimal import Decimal, ROUND_HALF_UP, localcontext
from email.utils import parsedate_to_datetime
from urllib.parse import urlencode, urlsplit, parse_qs

__version__ = "0.1.25"
_AGENT_ORIGINS = frozenset(("https://howsure-web.vercel.app", "https://www.howsure.com"))
MAX_BYTES = 2_000_000
_CHECK_ID = re.compile(r"[a-z0-9][a-z0-9-]{0,159}\Z")
_POLY = re.compile(r"polymarket:condition-sha256:[a-f0-9]{64}\Z")
_HIP = re.compile(r"hip4:mainnet:outcome:(0|[1-9][0-9]*)\Z")
_GENERATION = re.compile(r"sha256:[a-f0-9]{64}\Z")
_HIP_MAX = (9_007_199_254_740_991 - 100_000_001) // 10


def _fed_calendar_response(value):
    """Validate only the new December/January projection; archived v1/v2 stay unchanged."""
    reading = value.get("contract_reading")
    calendar = reading.get("calendar") if isinstance(reading, dict) else None
    has_next = isinstance(calendar, dict) and "nextMeeting" in calendar
    has_v3 = any(isinstance(source.get("locator"), str) and source["locator"].endswith("fed-meeting-v3") for source in value["sources"])
    if not has_next and not has_v3:
        return True
    if not isinstance(reading, dict) or reading.get("family") != "fed-meeting-rate-change" or not isinstance(calendar, dict):
        return False
    normalize = lambda text: re.sub(r"\s+", " ", unicodedata.normalize("NFC", text).replace("’", "'").replace("‘", "'").replace("–", "-").replace("—", "-")).strip()
    months = "January February March April May June July August September October November December".split()
    month_pattern = "(?:" + "|".join(months) + ")"
    contract = value["contract"]
    if not isinstance(contract.get("description"), str) or not isinstance(contract.get("resolutionSource"), str):
        return False
    calendar_url = "https://www.federalreserve.gov/monetarypolicy/fomccalendars.htm"
    rate_url = "https://www.federalreserve.gov/monetarypolicy/openmarket.htm"
    if contract["resolutionSource"].strip() != calendar_url:
        return False
    question = normalize(contract["question"])
    no_change = re.fullmatch(r"Will there be no change in Fed interest rates after the (" + month_pattern + r") (20\d{2}) meeting\?", question)
    change = re.fullmatch(r"Will the Fed (decrease|increase) interest rates by ([1-9]\d{0,2}\+?) bps after the (" + month_pattern + r") (20\d{2}) meeting\?", question)
    if not no_change and not change:
        return False
    month, year = (no_change[1], int(no_change[2])) if no_change else (change[3], int(change[4]))
    if change and int(change[2].rstrip("+")) % 25:
        return False
    terms = normalize(contract["description"])
    dates = re.search(r"The resolution source for this market is the FOMC's statement after its meeting scheduled for (" + month_pattern + r") (\d{1,2})-(\d{1,2}), (20\d{2}) according to the official calendar:", terms)
    if not dates or dates[1] != month or int(dates[4]) != year:
        return False
    first, last = int(dates[2]), int(dates[3])
    def valid_days(year, month, first, last):
        try:
            return 0 < first < last and datetime(year, month, first) < datetime(year, month, last)
        except ValueError:
            return False
    if not valid_days(year, months.index(month) + 1, first, last):
        return False
    expected_terms = f'The FED interest rates are defined in this market by the upper bound of the target federal funds range. The decisions on the target federal funds range are made by the Federal Open Market Committee (FOMC) meetings. This market will resolve to the amount of basis points the upper bound of the target federal funds rate is changed by versus the level it was prior to the Federal Reserve\'s {month} {year} meeting. If the target federal funds rate is changed to a level not expressed in the displayed options, the change will be rounded up to the nearest 25 and will resolve to the relevant bracket. (e.g. if there\'s a cut/increase of 12.5 bps it will be considered to be 25 bps) The resolution source for this market is the FOMC\'s statement after its meeting scheduled for {month} {first}-{last}, {year} according to the official calendar: {calendar_url}. The level and change of the target federal funds rate is also published at the official website of the Federal Reserve at {rate_url}. This market may resolve as soon as the FOMC\'s statement for their {month} meeting with relevant data is issued. If no statement is released by the end date of the next scheduled meeting, this market will resolve to the "No change" bracket.'
    rules = contract.get("resolutionRules")
    if terms != expected_terms or not (rules is None or isinstance(rules, str) and normalize(rules) == terms):
        return False
    venue = [source for source in value["sources"] if source["id"] == "venue-contract"]
    sources = [source for source in value["sources"] if source["id"] == "federal-reserve-fomc-calendar"]
    if len(venue) != 1 or venue[0]["status"] != "collected" or venue[0]["url"] != value["identity"]["venueUrl"] or not isinstance(venue[0]["excerpt"], str) or normalize(venue[0]["excerpt"]) != terms or len(sources) != 1:
        return False
    source = sources[0]
    source_ids = [source["id"]]
    expected_calendar = {"status": "unavailable", "text": "The retained calendar excerpt is incomplete or uses an unsupported format or source location, so it cannot corroborate these meeting dates. This does not establish a date disagreement.", "sourceIds": source_ids}
    locator = f"{year} FOMC Meetings · complete December and next-year January entries plus panel footers and schedule note · fed-meeting-v3"
    parsed = None
    if month == "December" and source["url"] == calendar_url and source.get("locator") == locator and source["status"] == "collected" and isinstance(source["excerpt"], str) and len(source["excerpt"]) <= 4000:
        marker = " · Listed publication links (destinations not fetched): "
        parts = source["excerpt"].split(marker)
        if len(parts) == 2:
            try:
                links = json.loads(parts[1])
                def valid_link(link):
                    if not isinstance(link, str) or re.search(r"[\s\\%\x00-\x1f\x7f]", link):
                        return False
                    prefix = "https://www.federalreserve.gov"
                    if not link.startswith(prefix):
                        return False
                    match = re.fullmatch(r"(?:/newsevents/pressreleases/monetary|/monetarypolicy/(?:files/)?(?:monetary|fomcminutes|fomcpresconf|fomcprojtabl))(20\d{2})(\d{2})(\d{2})(?:[a-z]\d?)?\.(?:htm|pdf)", link[len(prefix):])
                    if not match or int(match[1]) != year or int(match[2]) != 12:
                        return False
                    try:
                        datetime(year, 12, int(match[3]))
                        return True
                    except ValueError:
                        return False
                valid_links = isinstance(links, list) and len(links) <= 12 and all(valid_link(link) for link in links) and json.dumps(sorted(set(links)), separators=(",", ":"), ensure_ascii=False) == parts[1]
                labels = r"(?: Statement: PDF \| HTML Implementation Note Press Conference(?: Projection Materials PDF \| HTML)?(?: Minutes: PDF \| HTML \(Released " + month_pattern + r" \d{2}, 20\d{2}\))?)?"
                footer = r"\* Meeting associated with a Summary of Economic Projections\."
                expression = r"(?P<year>20\d{2}) FOMC Meetings December (?P<first>\d{1,2})-(?P<last>\d{1,2})(?:\*)?" + labels + " " + footer + r" (?P<nextYear>20\d{2}) FOMC Meetings January (?P<nextFirst>\d{1,2})-(?P<nextLast>\d{1,2})(?:\*)?" + labels + " " + footer + r" Note: A two-day meeting is scheduled for January (?P<noteFirst>\d{1,2})-(?P<noteLast>\d{1,2}), (?P<noteYear>20\d{2})\. Each meeting date is tentative until confirmed at the meeting immediately preceding it\."
                match = re.fullmatch(expression, normalize(parts[0])) if valid_links else None
                if match:
                    candidate = {key: int(item) for key, item in match.groupdict().items()}
                    if valid_days(candidate["year"], 12, candidate["first"], candidate["last"]) and valid_days(candidate["nextYear"], 1, candidate["nextFirst"], candidate["nextLast"]) and valid_days(candidate["noteYear"], 1, candidate["noteFirst"], candidate["noteLast"]) and candidate["nextYear"] == candidate["year"] + 1 and candidate["noteYear"] > candidate["nextYear"]:
                        parsed = candidate
            except (ValueError, TypeError):
                pass
    if parsed and (parsed["year"] != year or parsed["first"] != first or parsed["last"] != last):
        expected_calendar = {"status": "mismatch", "text": "The retained calendar passage gives meeting dates or a year that differ from these contract conditions. Reconcile the source and venue terms before relying on the schedule.", "sourceIds": source_ids}
    elif parsed:
        start_date = f'{parsed["nextYear"]}-01-{parsed["nextFirst"]:02d}'
        end_date = f'{parsed["nextYear"]}-01-{parsed["nextLast"]:02d}'
        expected_calendar = {"status": "matched", "sourceIds": source_ids,
            "text": f'The retained Federal Reserve calendar lists December {first}–{last}, {year}, matching this contract\'s stated dates. Its next listed scheduled meeting is January {parsed["nextFirst"]}–{parsed["nextLast"]}, {parsed["nextYear"]}. Both dates carry the calendar\'s tentative-date qualification: the calendar says each meeting date is tentative until confirmed at the meeting immediately preceding it; this capture does not establish that confirmation. The contract\'s no-statement exception refers to the end date of that next scheduled meeting, currently {end_date}; its exact time and timezone are not supplied. The shared note\'s January {parsed["noteFirst"]}–{parsed["noteLast"]}, {parsed["noteYear"]} meeting is later and is not this deadline. This schedule does not establish an absence of a statement, the fallback result, the policy decision or venue settlement.',
            "nextMeeting": {"startDate": start_date, "endDate": end_date, "status": "tentative", "confirmationEstablished": False,
                "noStatementCutoff": {"date": end_date, "time": None, "timeZone": None, "basis": "end_date_of_next_scheduled_meeting", "exceptionEstablished": False}}}
    next_meeting = calendar.get("nextMeeting")
    if has_next and (not isinstance(next_meeting, dict) or next_meeting.get("confirmationEstablished") is not False or not isinstance(next_meeting.get("noStatementCutoff"), dict) or next_meeting["noStatementCutoff"].get("exceptionEstablished") is not False):
        return False
    if calendar != expected_calendar:
        return False
    # Keep the new human/export claim bound to the same dates as the typed field.
    conditions = reading.get("conditions")
    if not isinstance(conditions, list):
        return False
    deadlines = [item for item in conditions if isinstance(item, dict) and item.get("label") == "No-statement deadline"]
    if "nextMeeting" not in expected_calendar:
        return not deadlines
    expected_deadline = {"label": "No-statement deadline",
        "value": f'The next listed scheduled meeting is January {parsed["nextFirst"]}–{parsed["nextLast"]}, {parsed["nextYear"]} (tentative; confirmation not established). Its end date, {end_date}, is the current calendar basis for the captured no-statement exception. The terms specify no exact time or timezone. Absence of a statement through that deadline has not been established; no fallback outcome or settlement follows from the calendar alone.',
        "sourceIds": ["venue-contract", *source_ids]}
    return deadlines == [expected_deadline]


def _decision_response(value):
    reading = value.get("contract_reading")
    if not isinstance(reading, dict) or "decision" not in reading:
        return True
    decision = reading["decision"]
    def day(item):
        try:
            return isinstance(item, str) and re.fullmatch(r"\d{4}-\d{2}-\d{2}", item) is not None and datetime.fromisoformat(item).date().isoformat() == item
        except ValueError:
            return False
    def bounds(item):
        return isinstance(item, dict) and all(type(item.get(key)) in (int, float) and math.isfinite(item[key]) and 0 <= item[key] <= 100 for key in ("lowerPercent", "upperPercent")) and item["lowerPercent"] <= item["upperPercent"]
    if value.get("collection_scope") != "fed_decision" or reading.get("family") != "fed-meeting-rate-change" or not isinstance(decision, dict):
        return False
    before, after, change, current = (decision.get(key) for key in ("before", "after", "changeBasisPoints", "currentRange"))
    required = ("status", "meetingDate", "statementDate", "releasedAt", "before", "after", "changeBasisPoints", "currentRange", "conditionAssessment", "summary", "sourceIds", "limitations", "settlementEstablished")
    if not all(key in decision for key in required) or decision["status"] not in ("observed", "pending", "unavailable", "unsupported") or not day(decision["meetingDate"]):
        return False
    if not (decision["statementDate"] is None or day(decision["statementDate"])) or not (decision["releasedAt"] is None or _time(decision["releasedAt"])) or not (before is None or bounds(before) and before.get("basis") == "derived_from_statement_action") or not (after is None or bounds(after)):
        return False
    if not (change is None or type(change) in (int, float) and math.isfinite(change)) or not (current is None or bounds(current) and day(current.get("effectiveDate")) and _time(current.get("observedAt"))):
        return False
    if decision["conditionAssessment"] not in ("YES_condition_met", "YES_condition_not_met", "unknown") or not _text(decision["summary"]) or not _texts(decision["sourceIds"]) or not _texts(decision["limitations"]) or decision["settlementEstablished"] is not False:
        return False
    ids = decision["sourceIds"]
    if len(set(ids)) != len(ids) or not all(any(source["id"] == item and source["status"] == "collected" for source in value["sources"]) for item in ids):
        return False
    instant = lambda stamp: datetime.fromisoformat(stamp.replace("Z", "+00:00"))
    if decision["status"] == "observed":
        source = next((row for row in value["sources"] if row["id"] == "federal-reserve-fomc-statement" and row["status"] == "collected"), None)
        if not source or source["url"] != "https://www.federalreserve.gov/newsevents/pressreleases/monetary" + decision["meetingDate"].replace("-", "") + "a.htm" or source["id"] not in ids or decision["statementDate"] != decision["meetingDate"] or decision["statementDate"] > source["checked_at"][:10] or before is None or after is None or change is None:
            return False
        if decision["releasedAt"] is not None and instant(decision["releasedAt"]) > instant(source["checked_at"]) or any(abs((after[key] - before[key]) * 100 - change) > 1e-7 for key in ("lowerPercent", "upperPercent")):
            return False
    elif any(decision[key] is not None for key in ("statementDate", "releasedAt", "before", "after", "changeBasisPoints")) or decision["conditionAssessment"] != "unknown":
        return False
    if current is not None:
        source = next((row for row in value["sources"] if row["id"] == "federal-reserve-target-range" and row["status"] == "collected"), None)
        if not source or source["url"] != "https://www.federalreserve.gov/monetarypolicy/openmarket.htm" or source["id"] not in ids or current["observedAt"] != source["checked_at"] or current["effectiveDate"] > source["checked_at"][:10]:
            return False
    return True


def _bracket_response(value, release):
    result = release.get("brackets")
    if value.get("collection_scope") != "gdp_release_brackets":
        return "brackets" not in release
    def matches(pattern, item):
        return isinstance(item, str) and re.fullmatch(pattern, item) is not None
    def identity(item):
        return isinstance(item, dict) and matches(r"[1-9]\d{0,99}", item.get("nativeMarketId")) and matches(r"0x[a-f0-9]{64}", item.get("conditionId")) and matches(r"[a-z0-9][a-z0-9-]{0,179}", item.get("nativeSlug")) and isinstance(item.get("question"), str) and bool(item["question"].strip()) and item.get("url") == f'https://polymarket.com/market/{item["nativeSlug"]}'
    if not isinstance(result, dict) or not all(key in result for key in ("status", "reason", "valuePercent", "atBoundary", "selected", "assignedContract", "event", "conditionAssessment", "summary", "sourceIds", "limitations")):
        return False
    number = result["valuePercent"]
    observation = release.get("observation") or {}
    if result["status"] not in ("assigned", "unknown") or not (result["reason"] is None or isinstance(result["reason"], str) and bool(result["reason"])) or not (number is None or type(number) in (int, float) and math.isfinite(number) and abs(number) <= 1000) or number != observation.get("valuePercent") or not (result["atBoundary"] is None or type(result["atBoundary"]) is bool) or not isinstance(result["summary"], str) or not _texts(result["sourceIds"]) or not _texts(result["limitations"]) or len(set(result["sourceIds"])) != len(result["sourceIds"]) or result["conditionAssessment"] != release["conditionAssessment"] or not (result["selected"] is None or identity(result["selected"])) or not (result["assignedContract"] is None or identity(result["assignedContract"])):
        return False
    selected, assigned, event = result["selected"], result["assignedContract"], result["event"]
    if result["status"] == "assigned":
        if result["reason"] is not None or number is None or type(result["atBoundary"]) is not bool or not selected or not assigned or not event or result["conditionAssessment"] != ("YES_condition_met" if selected["nativeMarketId"] == assigned["nativeMarketId"] else "YES_condition_not_met"):
            return False
    elif not result["reason"] or assigned is not None or result["conditionAssessment"] != "unknown":
        return False
    if event is None:
        return selected is None and result["sourceIds"] == [] and result["status"] == "unknown"
    source = next((row for row in value["sources"] if row["id"] == "polymarket-gdp-event-brackets" and row["status"] == "collected"), None)
    instant = lambda stamp: datetime.fromisoformat(stamp.replace("Z", "+00:00"))
    if not isinstance(event, dict) or not source or not selected or result["sourceIds"] != [source["id"]] or not matches(r"[1-9]\d{0,99}", event.get("eventId")) or not matches(r"[a-z0-9][a-z0-9-]{0,179}", event.get("eventSlug")) or event.get("eventUrl") != f'https://polymarket.com/event/{event["eventSlug"]}' or source["url"] != event["eventUrl"] or event.get("apiUrl") not in (f'https://gamma-api.polymarket.com/events/slug/{event["eventSlug"]}', f'https://gamma-api.polymarket.com/events/{event["eventId"]}') or not matches(r"[a-f0-9]{64}", event.get("responseSha256")) or event.get("checkedAt") != source["checked_at"] or instant(event["checkedAt"]) < instant(value["identity"]["capturedAt"]) or type(event.get("marketCount")) is not int or not 3 <= event["marketCount"] <= 16 or source["locator"] != "Complete markets array from exact event metadata; closed contracts retained" or len(source["excerpt"].encode("utf-8")) > 32_000:
        return False
    try:
        roster = json.loads(source["excerpt"])
    except ValueError:
        return False
    def same(a, b):
        return isinstance(a, dict) and all(a.get(key) == b[key] for key in ("nativeMarketId", "conditionId", "nativeSlug", "question"))
    if not isinstance(roster, dict) or roster.get("schemaVersion") != 1 or not all(roster.get(key) == event[key] for key in ("eventId", "eventSlug", "eventUrl", "apiUrl", "responseSha256", "marketCount")) or not isinstance(roster.get("contracts"), list) or len(roster["contracts"]) != event["marketCount"] or not same(roster.get("selected"), selected) or roster["selected"].get("metadataResponseSha256") != value["identity"].get("responseSha256") or selected["nativeMarketId"] != value["identity"]["identityRecord"]["id"] or selected["conditionId"] != value["identity"]["identityRecord"]["conditionId"] or selected["nativeSlug"] != value["market_slug"] or selected["question"] != value["contract"]["question"] or not any(same(row, selected) for row in roster["contracts"]) or assigned and not any(same(row, assigned) for row in roster["contracts"]):
        return False
    return True


_GDP_HISTORICAL_INDEX = 'BEA full schedule · complete Q4 2025 Advance and available Third Estimate rows · gdp-release-index-v2'
_GDP_RESCHEDULED_ADVANCE = 'BEA rescheduled Advance Estimate · title, release time, complete opening real-GDP paragraph, matching SAAR table and postponement notice · gdp-advance-rescheduled-v2'
_GDP_HISTORICAL_THIRD = 'BEA historical Third Estimate · title, release time, complete opening real-GDP paragraph and full vintage-labelled real-GDP table row · gdp-historical-revision-v1'
_GDP_THIRD_TITLE = 'GDP (Third Estimate), Industries, Corporate Profits, State GDP, and State Personal Income, 4th Quarter and Year 2025'
_GDP_THIRD_URL = 'https://www.bea.gov/news/2026/gdp-third-estimate-industries-corporate-profits-state-gdp-and-state-personal-income-4th'
_GDP_POSTPONEMENT = 'The advance report for the fourth quarter of 2025, originally scheduled for January 29, 2026, was rescheduled due to the October–November 2025 government shutdown.'


def _gdp_historical(required):
    return (required['quarter'], required['year'], required['expectedAdvanceDate']) == (4, 2025, '2026-01-29')


def _gdp_index(source, required):
    """A changed date requires the exact bounded historical schedule variant."""
    if not source or source['status'] != 'collected' or source.get('reason') is not None or source['id'] != 'bea-gdp-release-index' or source['url'] != 'https://www.bea.gov/news/schedule/full':
        return None
    historical = _gdp_historical(required) and source['locator'] == _GDP_HISTORICAL_INDEX
    if not historical and source['locator'] != 'BEA full schedule · year and complete selected Advance Estimate row · gdp-release-index-v1':
        return None
    lines = source['excerpt'].split('\n')
    quarter, year = required['quarter'], required['year']
    title = f"GDP (Advance Estimate), {('1st', '2nd', '3rd', '4th')[quarter - 1]} Quarter" + (' and Year' if quarter == 4 else '') + f' {year}'
    date = '2026-02-20' if historical else required['expectedAdvanceDate']
    named = datetime.fromisoformat(date).strftime('%B ') + str(int(date[8:])) + ', ' + date[:4]
    url = f"https://www.bea.gov/news/{required['expectedAdvanceDate'][:4]}/gdp-advance-estimate-{('1st', '2nd', '3rd', '4th')[quarter - 1]}-quarter" + ('-and-year' if quarter == 4 else '') + f'-{year}'
    if len(lines) not in ((5, 9) if historical else (5,)) or lines[:3] != ['BEA full release schedule · Year ' + required['expectedAdvanceDate'][:4], title, 'Scheduled date: ' + named] or not re.fullmatch(r'Listed time: (?:1[0-2]|[1-9]):[0-5]\d (?:AM|PM) \(timezone not supplied\)', lines[3]) or lines[4] not in ('Listed release: Not listed', 'Listed release: ' + url):
        return None
    revision = len(lines) == 9
    if revision and lines[5:] != ['Revision title: ' + _GDP_THIRD_TITLE, 'Revision scheduled date: April 9, 2026', 'Revision listed time: 8:30 AM (timezone not supplied)', 'Revision listed release: ' + _GDP_THIRD_URL]:
        return None
    return {'date': date, 'url': url if lines[4] != 'Listed release: Not listed' else None, 'revision': revision}


def _gdp_paragraph(paragraph, required, vintage):
    number = r'((?:0|[1-9]\d{0,2})(?:\.\d{1,2})?)'
    if _gdp_historical(required):
        match = re.fullmatch(r'Real gross domestic product \(GDP\) (increased|decreased) at an annual rate of ' + number + r' percent in the fourth quarter of 2025 \(October, November, and December\), according to the ' + vintage + r' estimate released today by the U\.S\. Bureau of Economic Analysis\.(?: In the third quarter(?: of 2025)?, real GDP (?:increased|decreased) (?:0|[1-9]\d{0,2})(?:\.\d{1,2})? percent\.)?', paragraph)
        if match:
            return float(match[2]) * (-1 if match[1] == 'decreased' else 1)
    words = ('first', 'second', 'third', 'fourth')
    periods = ('January, February, and March', 'April, May, and June', 'July, August, and September', 'October, November, and December')
    quarter = required['quarter']
    match = re.fullmatch(r'Real gross domestic product \(GDP\) (increased|decreased) at an annual rate of ' + number + r' percent in the ' + words[quarter - 1] + ' quarter of ' + str(required['year']) + r' \(' + periods[quarter - 1] + r'\), according to the ' + vintage + r' estimate released today by the U\.S\. Bureau of Economic Analysis \(BEA\)\.(?: In the ' + words[(quarter + 2) % 4] + r' quarter, real GDP (?:increased|decreased) (?:0|[1-9]\d{0,2})(?:\.\d{1,2})? percent(?: \(revised\))?\.)?', paragraph)
    return float(match[2]) * (-1 if match[1] == 'decreased' else 1) if match else None


def _gdp_advance(source, required, index):
    if not source or not index or source['status'] != 'collected' or source.get('reason') is not None or source['id'] != 'bea-gdp-advance-release' or source['url'] != index['url']:
        return None
    rescheduled = _gdp_historical(required) and source['locator'] == _GDP_RESCHEDULED_ADVANCE
    if not rescheduled and source['locator'] != 'BEA Advance Estimate · title, release time, complete opening real-GDP paragraph and matching SAAR table cells · gdp-advance-release-v1':
        return None
    lines = source['excerpt'].split('\n')
    quarter, year = required['quarter'], required['year']
    title = f"GDP (Advance Estimate), {('1st', '2nd', '3rd', '4th')[quarter - 1]} Quarter" + (' and Year' if quarter == 4 else '') + f' {year}'
    if len(lines) != (6 if rescheduled else 5) or lines[0] != title or not lines[1].startswith('Release: ') or not lines[2].startswith('Opening paragraph: '):
        return None
    stamp, number = _macro_publication_time(lines[1][9:], True), _gdp_paragraph(lines[2][19:], required, 'advance')
    prior_quarter, prior_year = (4, year - 1) if quarter == 1 else (quarter - 1, year)
    units = 'Real GDP and Related Measures [Percent change (SAAR) from 2025 Q3 to Q4]' if rescheduled else f'Real GDP and Related Measures [Percent change (SAAR) from {prior_year}:Q{prior_quarter} to {year}:Q{quarter}]'
    if not stamp or stamp[:10] != ('2026-02-20' if rescheduled else required['expectedAdvanceDate']) or stamp[:10] != index['date'] or stamp > source['checked_at'] or number is None or lines[3] != 'Table units: ' + units or lines[4] != 'Advance Estimate · Real GDP: ' + format(number, '.15g') or rescheduled and lines[5] != 'Reschedule notice: ' + _GDP_POSTPONEMENT:
        return None
    facts = dict(valuePercent=number, quarter=quarter, year=year, vintage='advance', publishedAt=stamp, sourceId=source['id'], url=source['url'], checkedAt=source['checked_at'])
    if rescheduled:
        facts['rescheduledFrom'] = required['expectedAdvanceDate']
    return facts


def _gdp_revision(source, required, index):
    if not _gdp_historical(required) or not index or not index['revision'] or not source or source['status'] != 'collected' or source.get('reason') is not None or source['id'] != 'bea-gdp-revision-release' or source['url'] != _GDP_THIRD_URL or source['locator'] != _GDP_HISTORICAL_THIRD:
        return None
    lines = source['excerpt'].split('\n')
    if len(lines) != 5 or lines[0] != _GDP_THIRD_TITLE or not lines[1].startswith('Release: ') or not lines[2].startswith('Opening paragraph: ') or lines[3] != 'Table units: Real GDP and Related Measures [Percent change (SAAR) from 2025:Q3 to 2025:Q4]':
        return None
    stamp, number = _macro_publication_time(lines[1][9:], True), _gdp_paragraph(lines[2][19:], required, 'third')
    numeric = r'(-?(?:0|[1-9]\d{0,2})(?:\.\d{1,2})?)'
    row = re.fullmatch(r'Real GDP · Advance Estimate: ' + numeric + r' · Second Estimate: ' + numeric + r' · Third Estimate: ' + numeric, lines[4])
    if not stamp or stamp[:10] != '2026-04-09' or stamp > source['checked_at'] or number is None or not row or float(row[3]) != number:
        return None
    return dict(valuePercent=number, quarter=4, year=2025, vintage='third', publishedDate=stamp[:10], sourceId=source['id'], url=source['url'], checkedAt=source['checked_at'])


def _release_response(value):
    reading = value.get("contract_reading")
    if not isinstance(reading, dict) or "release" not in reading:
        return not (isinstance(reading, dict) and reading.get("family") == "us-gdp-growth" and value.get("collection_scope") in ("gdp_release", "gdp_release_brackets"))
    release = reading["release"]
    def day(item):
        try:
            return isinstance(item, str) and re.fullmatch(r"\d{4}-\d{2}-\d{2}", item) is not None and datetime.fromisoformat(item).date().isoformat() == item
        except ValueError:
            return False
    def period(item):
        return isinstance(item, dict) and type(item.get("quarter")) is int and 1 <= item["quarter"] <= 4 and type(item.get("year")) is int and 2000 <= item["year"] <= 2099
    def figure(item):
        return period(item) and type(item.get("valuePercent")) in (int, float) and math.isfinite(item["valuePercent"]) and _time(item.get("checkedAt"))
    if value.get("collection_scope") not in ("gdp_release", "gdp_release_brackets") or reading.get("family") != "us-gdp-growth" or not isinstance(release, dict):
        return False
    required = release.get("required")
    if not all(key in release for key in ("status", "required", "observation", "latestRevision", "conditionAssessment", "summary", "sourceIds", "limitations", "settlementEstablished")) or release["status"] not in ("observed", "pending", "unavailable", "unsupported") or not period(required) or required.get("vintage") != "advance" or not day(required.get("expectedAdvanceDate")):
        return False
    if release["conditionAssessment"] not in ("YES_condition_met", "YES_condition_not_met", "unknown") or not _text(release["summary"]) or not _texts(release["sourceIds"]) or not _texts(release["limitations"]) or release["settlementEstablished"] is not False:
        return False
    ids = release["sourceIds"]
    if len(set(ids)) != len(ids) or not all(any(source["id"] == item and source["status"] == "collected" for source in value["sources"]) for item in ids):
        return False
    observation, revision = release["observation"], release["latestRevision"]
    instant = lambda stamp: datetime.fromisoformat(stamp.replace("Z", "+00:00"))
    if release["status"] == "observed":
        if not figure(observation) or observation.get("vintage") != "advance" or observation["quarter"] != required["quarter"] or observation["year"] != required["year"] or not _time(observation.get("publishedAt"))  or instant(observation["publishedAt"]) > instant(observation["checkedAt"]) or observation.get("sourceId") != "bea-gdp-advance-release":
            return False
        source = next((row for row in value["sources"] if row["id"] == observation["sourceId"] and row["status"] == "collected"), None)
        index = next((row for row in value["sources"] if row["id"] == "bea-gdp-release-index" and row["status"] == "collected"), None)
        ordinal = ("1st", "2nd", "3rd", "4th")[required["quarter"] - 1]
        expected = f'https://www.bea.gov/news/{required["expectedAdvanceDate"][:4]}/gdp-advance-estimate-{ordinal}-quarter' + ("-and-year" if required["quarter"] == 4 else "") + f'-{required["year"]}'
        if not source or source["url"] != expected or observation.get("url") != source["url"] or observation["checkedAt"] != source["checked_at"] or not index or index["url"] != "https://www.bea.gov/news/schedule/full" or source["id"] not in ids or index["id"] not in ids:
            return False
        if source["checked_at"] < value["identity"]["capturedAt"] or index["checked_at"] < value["identity"]["capturedAt"] or observation != _gdp_advance(source, required, _gdp_index(index, required)):
            return False
    elif observation is not None or release["conditionAssessment"] != "unknown":
        return False
    if revision is not None:
        if not figure(revision) or revision.get("vintage") not in ("second", "third") or revision["quarter"] != required["quarter"] or revision["year"] != required["year"] or not day(revision.get("publishedDate")) or revision["publishedDate"] <= required["expectedAdvanceDate"] or revision["publishedDate"] > revision["checkedAt"][:10] or revision.get("sourceId") not in ("bea-gdp-current", "bea-gdp-revision-release"):
            return False
        source = next((row for row in value["sources"] if row["id"] == revision["sourceId"] and row["status"] == "collected"), None)
        if revision["sourceId"] == "bea-gdp-revision-release":
            index = next((row for row in value["sources"] if row["id"] == "bea-gdp-release-index" and row["status"] == "collected"), None)
            if not source or source["id"] not in ids or not index or index["id"] not in ids or source["checked_at"] < value["identity"]["capturedAt"] or index["checked_at"] < value["identity"]["capturedAt"] or revision != _gdp_revision(source, required, _gdp_index(index, required)):
                return False
        else:
            marker = ' · Listed publication links (destinations not fetched): '
            if not source or source["url"] != "https://www.bea.gov/data/gdp/gross-domestic-product" or source["checked_at"] != revision["checkedAt"] or source["id"] not in ids or not isinstance(revision.get("url"), str) or not re.fullmatch(r"https://www\.bea\.gov/news/20\d{2}/[a-z0-9-]+", revision["url"]) or source["excerpt"].count(marker) != 1:
                return False
            try:
                links = json.loads(source["excerpt"].split(marker)[1])
            except (ValueError, IndexError):
                return False
            if links != [revision["url"]]:
                return False
    return _bracket_response(value, release)


_MACRO_MONTHS = ("January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December")


def _macro_publication_time(label, pce):
    """Validate the retained printed label, including New York DST and weekday."""
    if pce:
        match = re.fullmatch(r"EMBARGOED UNTIL RELEASE AT (1[0-2]|[1-9]):([0-5]\d) (a|p)\.m\. (EDT|EST), (Sunday|Monday|Tuesday|Wednesday|Thursday|Friday|Saturday), ([A-Za-z]+) ([1-9]\d?), (20\d{2})", label)
        if not match or match[6] not in _MACRO_MONTHS:
            return None
        hour = int(match[1]) % 12 + (12 if match[3] == "p" else 0)
        stamp = datetime(int(match[8]), _MACRO_MONTHS.index(match[6]) + 1, int(match[7]), hour, int(match[2]), tzinfo=ZoneInfo("America/New_York"))
        if stamp.tzname() != match[4] or ("Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday")[stamp.weekday()] != match[5]:
            return None
    else:
        match = re.fullmatch(r"8:30 a\.m\. \(ET\) (Sunday|Monday|Tuesday|Wednesday|Thursday|Friday|Saturday), ([A-Za-z]+) ([1-9]\d?), (20\d{2})", label)
        if not match or match[2] not in _MACRO_MONTHS:
            return None
        stamp = datetime(int(match[4]), _MACRO_MONTHS.index(match[2]) + 1, int(match[3]), 8, 30, tzinfo=ZoneInfo("America/New_York"))
        if ("Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday")[stamp.weekday()] != match[1]:
            return None
    return stamp.astimezone(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z")



_PCE_FORWARD_ANNUAL_NOTICE = ('Annual Update of the National and Regional Economic Accounts '
    'With improvements in the concurrent production of BEA statistics, the 2026 annual updates of national, industry, and regional data will begin on the same day for the first time: September 30, 2026. '
    'The annual update of the National Economic Accounts includes GDP, gross domestic income, GDP by industry, monthly personal income and outlays, and related statistics in the National Income and Product Accounts and the Industry Economic Accounts. '
    'The update of the Regional Economic Accounts includes GDP by state and by county, personal income by state and by county, and related statistics. '
    'For details, refer to "Information on 2026 Annual Updates to the National, Industry, State, and County Statistics."')
_PCE_JUNE_FORWARD_ANNUAL_NOTICE = _PCE_FORWARD_ANNUAL_NOTICE.replace('national, industry, and regional', 'national, industry,and regional')
_PCE_ARCHIVE_NOTICE = 'Note. With the next release, today’s data will be superseded, and the links above will reflect the latest data. The original data featured in this release can then be accessed in BEA’s Data Archive.'
_PCE_JUNE_ARCHIVE_NOTICE = _PCE_ARCHIVE_NOTICE.replace('With the next release,', 'With the next release of PIO,')


def _pce_annual_notice(value, month, year, release_day):
    """Keep complete applied notices and the exact retained June/July variants."""
    if value is None:
        return True
    if not isinstance(value, str):
        return False
    if value == _PCE_FORWARD_ANNUAL_NOTICE:
        return month == "July" and year == 2026 and release_day == "2026-08-26"
    if value == _PCE_JUNE_FORWARD_ANNUAL_NOTICE:
        return month == "June" and year == 2026 and release_day == "2026-07-30"
    applied = re.fullmatch(r'Today’s release presents monthly results from the annual update of the National Economic Accounts\. The revisions for estimates of personal income and outlays begin with January (19\d{2}|20\d{2})\. Refer to "Information on (20\d{2}) Annual Updates to the National, Industry, State, and County Statistics" for more information\.', value)
    return bool(applied and int(applied[1]) <= year and int(applied[2]) == int(release_day[:4]))


_MACRO_PCE_TERMS = 'This is a market about core inflation (excluding food and energy) over the 1-month period ending {month} {year}, seasonally adjusted, as reported by the Bureau of Economic Analysis. This market will resolve to the percentage change in the Personal Consumption Expenditures Price Index excluding food and energy (Core PCE) over the 1-month period ending in {month} {year} according to the monthly Bureau of Economic Analysis (BEA) report. The resolution source for this market will be the BEA Personal Income and Outlays report for {month} {year} (https://www.bea.gov/data/personal-consumption-expenditures-price-index), currently scheduled to be released on {releaseMonth} {day}, {releaseYear}, at 8:30 AM ET. Resolution of this market will take place upon release of the aforementioned data. Note: the resolution source for this market will be the official monthly BEA Personal Income and Outlays news release, which reports core inflation (all items less food and energy) over 1-month periods to only one decimal point (e.g., {precisionExample}%). Thus, this is the level of precision that will be used when resolving the market. For the avoidance of doubt, this market resolves on the core PCE figure (the PCE price index excluding food and energy), not the headline all-items (total) PCE price index figure. If the BEA does not release the relevant figures on the scheduled date, this market may remain open up until the scheduled release time of the next Personal Income and Outlays report (https://www.bea.gov/news/schedule). If the information is not released by that time, this market will resolve according to the figures of the most recent previous month with available data.'
_MACRO_CPI_TERMS = 'This is a market about the one-month percent change in the Consumer Price Index for All Urban Consumers excluding food and energy in {month} {year} as reported by the Bureau of Labor Statistics. This market will resolve to the one-month percentage change in the Consumer Price Index for All Urban Consumers excluding food and energy (Core CPI-U) in {month} {year} according to the monthly Bureau of Labor Statistics (BLS) report (seasonally adjusted change from the preceding month). The resolution source for this market will be the BLS Consumer Price Index report released for {month} {year} (https://www.bls.gov/bls/news-release/cpi.htm), currently scheduled to be released on {releaseMonth} {day}, {releaseYear}, at 8:30 AM ET. Resolution of this market will take place upon release of the aforementioned data. Note: the resolution source for this market will be the official monthly BLS CPI news release, which reports core inflation (all items less food and energy) over 1-month periods to only one decimal point (e.g., 0.3%). Thus, this is the level of precision that will be used when resolving the market. For the avoidance of doubt, this market resolves on the core CPI figure (the all items index excluding food and energy), not the headline all items CPI figure. If the BLS does not release the relevant figures on the scheduled date, this market may remain open up until the scheduled release time of the next CPI report (https://www.bls.gov/schedule). If the information is not released by that time, this market will resolve according to the figures of the most recent previous month with available data.'

def _macro_contract_context(value, pce):
    """Bind the operator and period to the complete retained venue template."""
    normalize = lambda text: ' '.join(unicodedata.normalize('NFC', text).replace('’', "'").replace('‘', "'").split())
    contract = value.get('contract')
    if not isinstance(contract, dict) or contract.get('venue') != 'polymarket' or not isinstance(contract.get('question'), str) or not isinstance(contract.get('description'), str):
        return None
    name = 'PCE' if pce else 'CPI'
    source_url = 'https://www.bea.gov/data/personal-consumption-expenditures-price-index' if pce else 'https://www.bls.gov/bls/news-release/cpi.htm'
    if contract.get('resolutionSource') is not None and (not isinstance(contract['resolutionSource'], str) or contract['resolutionSource'].strip() != source_url):
        return None
    question, terms = normalize(contract['question']), normalize(contract['description'])
    number = r'(-?(?:0|[1-9]\d{0,2})\.\d)'
    question_match = re.fullmatch(r'Will Core ' + name + r' MoM be ' + number + r'%( or more)? in ([A-Za-z]+)\?', question)
    opening = r'This is a market about core inflation \(excluding food and energy\) over the 1-month period ending ([A-Za-z]+) (20\d{2}), seasonally adjusted, as reported by the Bureau of Economic Analysis\.' if pce else r'This is a market about the one-month percent change in the Consumer Price Index for All Urban Consumers excluding food and energy in ([A-Za-z]+) (20\d{2}) as reported by the Bureau of Labor Statistics\.'
    period = re.match(opening, terms)
    schedule = re.search(r'currently scheduled to be released on ([A-Za-z]+) ([1-9]\d?), (20\d{2}), at 8:30 AM ET\.', terms)
    example = re.search(r'only one decimal point \(e\.g\., ' + number + r'%\)\.', terms) if pce else None
    if not question_match or not period or not schedule or pce and (not example or example[1] == '-0.0'):
        return None
    threshold, upper = float(question_match[1]), bool(question_match[2])
    month, year, release_month, day, release_year = period[1], int(period[2]), schedule[1], int(schedule[2]), int(schedule[3])
    if question_match[1] == '-0.0' or upper and threshold != 0.6 or month not in _MACRO_MONTHS or release_month not in _MACRO_MONTHS or question_match[3] != month:
        return None
    release_date = datetime(release_year, _MACRO_MONTHS.index(release_month) + 1, day)
    following_year, following_month = (year + 1, 1) if month == 'December' else (year, _MACRO_MONTHS.index(month) + 2)
    if release_year < year or release_year > year + 1 or release_date < datetime(following_year, following_month, 1):
        return None
    expected = (_MACRO_PCE_TERMS if pce else _MACRO_CPI_TERMS).format(month=month, year=year, releaseMonth=release_month, day=day, releaseYear=release_year, precisionExample=example[1] if pce else '0.3')
    old = 'core PCE figure (the PCE price index excluding food and energy), not' if pce else 'core CPI figure (the all items index excluding food and energy), not'
    new = 'core PCE figure — the PCE price index excluding food and energy — not' if pce else 'core CPI figure — the all items index excluding food and energy — not'
    if terms not in (expected, expected.replace(old, new)) or contract.get('resolutionRules') is not None and (not isinstance(contract['resolutionRules'], str) or normalize(contract['resolutionRules']) != terms):
        return None
    venue = [row for row in value['sources'] if row['id'] == 'venue-contract']
    if len(venue) != 1 or venue[0]['status'] != 'collected' or venue[0]['reason'] is not None or not isinstance(venue[0]['excerpt'], str) or normalize(venue[0]['excerpt']) != terms or venue[0]['url'] != value['identity']['venueUrl'] or venue[0]['checked_at'] != value['identity']['capturedAt'] or venue[0]['locator'] != ('description field in exact market metadata' if contract.get('resolutionRules') is None else 'resolutionRules field in exact market metadata'):
        return None
    return {'month': month, 'year': year, 'day': release_date.date().isoformat(), 'comparison': 'greater_than_or_equal' if upper else 'equal', 'threshold': threshold}

def _monthly_threshold_comparison(number):
    valid = type(number) in (int, float) and math.isfinite(number) and abs(number) < 1000 and not (number == 0 and math.copysign(1, number) < 0) and float(f'{number:.1f}') == number
    reported = number if valid else None
    status = 'unavailable' if reported is None else 'meets_numeric_threshold' if reported >= 0.6 else 'below_numeric_threshold'
    summary = 'No supported one-decimal reported monthly value is available for comparison with the inclusive 0.6% threshold. Missing evidence is not NO or a triggered fallback.' if reported is None else f"The retained one-decimal reported value of {reported:.1f}% " + ('meets' if status == 'meets_numeric_threshold' else 'is below') + ' the inclusive 0.6% numeric threshold; exactly 0.6% is included. This arithmetic does not establish a qualifying release-time contract result or venue settlement.'
    return dict(comparison='greater_than_or_equal', thresholdPercent=0.6, reportedValuePercent=reported, status=status, qualifyingConditionEstablished=False, summary=summary)


def _macro_release_response(value):
    """Source-bound monthly facts only. HTML extraction remains server-owned."""
    try:
        reading = value.get("contract_reading")
        if reading is None:
            return True
        if not isinstance(reading, dict):
            return False
        for pce, scope, family, field in ((True, "pce_release", "us-core-pce", "pceRelease"), (False, "cpi_release", "us-core-cpi", "cpiRelease")):
            result = reading.get(field)
            if result is None:
                if field in reading or value.get("collection_scope") == scope and reading.get("family") == family:
                    return False
                continue
            required = result.get("required") if isinstance(result, dict) else None
            if value.get("collection_scope") != scope or reading.get("family") != family or not isinstance(required, dict):
                return False
            month, year, day = (required.get(key) for key in ("month", "year", "expectedReleaseDate"))
            metric = "core_pce" if pce else "core_cpi"
            context = _macro_contract_context(value, pce)
            if not context or (month, year, day) != (context["month"], context["year"], context["day"]):
                return False
            if month not in _MACRO_MONTHS or type(year) is not int or not 2000 <= year <= 2099 or not isinstance(day, str) or not _time(day + "T00:00:00.000Z") or required.get("metric") != metric or required.get("horizon") != "one_month" or required.get("precisionDecimalPlaces") != 1:
                return False
            if not pce and required.get("seasonalAdjustment") != "seasonally_adjusted":
                return False
            if result.get("status") not in ("observed", "pending", "unavailable", "unsupported") or result.get("conditionAssessment") != "unknown" or result.get("settlementEstablished") is not False or not _text(result.get("summary")) or not _texts(result.get("sourceIds")) or not _texts(result.get("limitations")):
                return False
            ids, observation = result["sourceIds"], result.get("observation")
            if context["comparison"] == "greater_than_or_equal":
                number = observation.get("valuePercent") if isinstance(observation, dict) else None
                comparison = result.get("reportedValueComparison")
                reported = comparison.get("reportedValuePercent") if isinstance(comparison, dict) else None
                if not isinstance(comparison, dict) or comparison.get("qualifyingConditionEstablished") is not False or type(comparison.get("thresholdPercent")) not in (int, float) or not (reported is None or type(reported) in (int, float) and math.isfinite(reported) and not (reported == 0 and math.copysign(1, reported) < 0)) or comparison != _monthly_threshold_comparison(number):
                    return False
            elif "reportedValueComparison" in result:
                return False
            if len(set(ids)) != len(ids) or not all(any(source["id"] == item and source["status"] == "collected" for source in value["sources"]) for item in ids):
                return False
            if result["status"] != "observed":
                if observation is not None:
                    return False
                if result["status"] == "pending":
                    index_id = "bea-pce-release-index" if pce else "bls-cpi-release-index"
                    index_url = "https://www.bea.gov/news/schedule/full" if pce else "https://www.bls.gov/bls/news-release/cpi.htm"
                    index = next((row for row in value["sources"] if row["id"] == index_id and row["status"] == "collected"), None)
                    if day <= value["captured_at"][:10] or not index or index["url"] != index_url or ids != [index_id] or index["checked_at"] < value["identity"]["capturedAt"]:
                        return False
                    index_lines = index["excerpt"].split("\n")
                    if pce and (len(index_lines) != 5 or index_lines[1] != f"Personal Income and Outlays, {month} {year}" or index_lines[4] != "Listed release: Not listed"):
                        return False
                continue
            if not isinstance(observation, dict) or any(observation.get(key) != required[key] for key in ("month", "year", "metric", "horizon", "precisionDecimalPlaces")) or observation.get("originalReleaseVerified") is not False:
                return False
            numbers = ("valuePercent", "headlineMonthlyPercent", "coreYearOverYearPercent", "headlineYearOverYearPercent")
            if any(type(observation.get(key)) not in (int, float) or not math.isfinite(observation[key]) or abs(observation[key]) > 1000 for key in numbers):
                return False
            source_id = "bea-pce-monthly-release" if pce else "bls-cpi-monthly-release"
            index_id = "bea-pce-release-index" if pce else "bls-cpi-release-index"
            cpi_archive = not pce and observation.get("sourceVersion") == "retained_archive_release"
            source_url = f'https://www.bea.gov/news/{day[:4]}/personal-income-and-outlays-{month.lower()}-{year}' if pce else observation.get("url") if cpi_archive else "https://www.bls.gov/news.release/cpi.nr0.htm"
            if cpi_archive:
                archive = re.fullmatch(r"https://www\.bls\.gov/news\.release/archives/cpi_(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])(20\d{2})\.htm", source_url) if isinstance(source_url, str) else None
                if not archive or f"{archive[3]}-{archive[1]}-{archive[2]}" != day:
                    return False
            index_url = "https://www.bea.gov/news/schedule/full" if pce else "https://www.bls.gov/bls/news-release/cpi.htm"
            source = next((row for row in value["sources"] if row["id"] == source_id and row["status"] == "collected"), None)
            index = next((row for row in value["sources"] if row["id"] == index_id and row["status"] == "collected"), None)
            if not source or not index or source["url"] != source_url or index["url"] != index_url or source_id not in ids or index_id not in ids or observation.get("sourceId") != source_id or observation.get("url") != source_url or observation.get("checkedAt") != source["checked_at"]:
                return False
            if not _time(observation.get("publishedAt")) or observation["publishedAt"][:10] != day or observation["publishedAt"] > source["checked_at"] or source["checked_at"] < value["identity"]["capturedAt"] or index["checked_at"] < value["identity"]["capturedAt"]:
                return False
            lines = source["excerpt"].split("\n")
            if pce:
                if len(lines) != 12 or lines[0] != f"Personal Income and Outlays, {month} {year}" or not lines[1].startswith("Release: ") or _macro_publication_time(lines[1][9:], True) != observation["publishedAt"] or observation.get("seasonalAdjustment") != "not_explicit_in_retained_passage" or observation.get("sourceVersion") != "retained_named_monthly_release":
                    return False
                number = r"((?:0|[1-9]\d{0,2})\.\d)"
                monthly = re.fullmatch(r"Monthly price paragraph: From the preceding month, the PCE price index for " + month + r" (increased|decreased) " + number + r" percent\. Excluding food and energy, the PCE price index (?:also )?(increased|decreased) " + number + r" percent\.", lines[2])
                yearly = re.fullmatch(r"Yearly price paragraph: From the same month one year ago, the PCE price index for " + month + r" (increased|decreased) " + number + r" percent\. Excluding food and energy, the PCE price index (increased|decreased) " + number + r" percent from one year ago\.", lines[3])
                if not monthly or not yearly:
                    return False
                signed = lambda match, position: float(match[position + 1]) * (-1 if match[position] == "decreased" else 1)
                if (observation["headlineMonthlyPercent"], observation["valuePercent"], observation["headlineYearOverYearPercent"], observation["coreYearOverYearPercent"]) != (signed(monthly, 1), signed(monthly, 3), signed(yearly, 1), signed(yearly, 3)):
                    return False
                archive_notice = observation.get("archiveNotice")
                archive_valid = archive_notice == _PCE_ARCHIVE_NOTICE or (archive_notice == _PCE_JUNE_ARCHIVE_NOTICE and month == "June" and year == 2026 and day == "2026-07-30")
                if not _pce_annual_notice(observation.get("annualUpdateNotice"), month, year, day) or not archive_valid:
                    return False
                if lines[4] != "Table units: Personal Income and Related Measures [Percent change from preceding month]" or lines[5] != f"Table months: {_MACRO_MONTHS[(_MACRO_MONTHS.index(month) + 11) % 12]} | {month}" or float(lines[6][28:]) != observation["headlineMonthlyPercent"] or float(lines[7][24:]) != observation["valuePercent"] or lines[8] != "Annual update: " + (observation.get("annualUpdateNotice") or "None retained") or lines[9] != "Archive notice: " + observation.get("archiveNotice", "") or lines[10] != "Seasonal adjustment: not explicit in retained passage" or lines[11] != "Version: retained named monthly release; original release bytes not verified":
                    return False
                index_lines = index["excerpt"].split("\n")
                if len(index_lines) != 5 or index_lines[1] != f"Personal Income and Outlays, {month} {year}" or index_lines[4] != "Listed release: " + source_url:
                    return False
            else:
                version = "retained_archive_release" if cpi_archive else "retained_current_summary"
                version_label = "Retained archive release; original release bytes not verified" if cpi_archive else "Retained current summary; original release bytes not verified"
                if len(lines) != 13 or lines[0] != f"Consumer Price Index - {month} {year}" or not lines[1].startswith("Release label: ") or _macro_publication_time(lines[1][15:], False) != observation["publishedAt"] or observation.get("seasonalAdjustment") != "seasonally_adjusted" or observation.get("sourceVersion") != version or lines[4] != "Table A monthly horizon: Seasonally adjusted changes from preceding month":
                    return False
                headline, core = lines[7][18:].split(" | "), lines[8][14:].split(" | ")
                if len(headline) != 8 or len(core) != 8 or (float(headline[6]), float(core[6]), float(headline[7]), float(core[7])) != (observation["headlineMonthlyPercent"], observation["valuePercent"], observation["headlineYearOverYearPercent"], observation["coreYearOverYearPercent"]) or lines[10] != "Seasonal revision notice: " + observation.get("revisionNotice", "") or lines[12] != "Version: " + version_label:
                    return False
                if not lines[9].startswith("Table A complete: ") or "All items " + " ".join(headline) not in lines[9] or "All items less food and energy " + " ".join(core) not in lines[9]:
                    return False
                if cpi_archive:
                    index_lines = index["excerpt"].split("\n")
                    caution = "Data in archived news releases may have been revised in subsequent releases. The latest data, including any revisions, may be obtained from the databases accessible on the program homepage: Consumer Price Indexes: databases."
                    if index_lines != ["BLS Consumer Price Index archive index", f"Requested reference period: {month} {year}", "Current edition: https://www.bls.gov/news.release/cpi.nr0.htm", "Exact archived release: " + source_url, "Archive caution: " + caution] or index["locator"] != "BLS CPI archive index · selected period, current-edition link and archive revision caution · cpi-release-index-v1" or source["locator"] != "BLS CPI archive · complete opening, Table A with monthly/annual headers, next-release label and seasonal-revision notice · cpi-archive-release-v1":
                        return False
                    short = ["Jan.", "Feb.", "Mar.", "Apr.", "May", "Jun.", "Jul.", "Aug.", "Sep.", "Oct.", "Nov.", "Dec."]
                    months = [divmod(year * 12 + _MACRO_MONTHS.index(month) - 6 + n, 12) for n in range(7)]
                    if lines[5] != "Table A months: " + " | ".join(f"{short[m]} {y}" for y, m in months) or lines[6] != f"Table A yearly horizon: Un-adjusted 12-mos. ended {short[_MACRO_MONTHS.index(month)]} {year}" or not lines[2].startswith("Opening release block: ") or f"CONSUMER PRICE INDEX - {month.upper()} {year}" not in lines[2]:
                        return False
                    def change(prefix, suffix, pattern=False):
                        matches = list(re.finditer(re.escape(prefix) + r"(?:(rose|increased|fell|decreased|declined) ((?:0|[1-9]\d{0,2})\.\d) percent|was unchanged)" + (suffix if pattern else re.escape(suffix)), lines[2][23:]))
                        if len(matches) != 1:
                            return None
                        match = matches[0]
                        return float(match[2]) * (-1 if match[1] in ("fell", "decreased", "declined") else 1) if match[1] else 0
                    previous_month = _MACRO_MONTHS[(_MACRO_MONTHS.index(month) + 11) % 12]
                    core_suffix = r"(?: in " + re.escape(month) + r"| after increasing (?:0|[1-9]\d{0,2})\.\d percent in " + re.escape(previous_month) + r"\.| after being unchanged in " + re.escape(previous_month) + r"\.)"
                    if (change("The index for all items less food and energy ", core_suffix, True), change("The Consumer Price Index for All Urban Consumers (CPI-U) ", " on a seasonally adjusted basis in " + month), change("The all items less food and energy index ", " over the year"), change("Over the last 12 months, the all items index ", " before seasonal adjustment")) != (observation["valuePercent"], observation["headlineMonthlyPercent"], observation["coreYearOverYearPercent"], observation["headlineYearOverYearPercent"]):
                        return False
                    core_prefix = r"The index for all items less food and energy (?:(?:rose|increased|fell|decreased|declined) (?:0|[1-9]\d{0,2})\.\d percent|was unchanged)"
                    prior = re.search(core_prefix + r" after increasing ((?:0|[1-9]\d{0,2})\.\d) percent in " + re.escape(previous_month) + r"\.", lines[2])
                    prior_unchanged = re.search(core_prefix + r" after being unchanged in " + re.escape(previous_month) + r"\.", lines[2])
                    revision = observation.get("revisionNotice", "")
                    if prior and float(prior[1]) != float(core[5]) or prior_unchanged and float(core[5]) != 0 or not revision.startswith("Revision of Seasonally Adjusted Indexes Seasonally adjusted data, including the U.S. city average all items index levels, are subject to revision for up to 5 years after their original release.") or "last 5 years of data" not in revision or re.search(r"\b(?:corrected|correction|errata|erratum|withdrawn|withdrawal|retracted|retraction)\b", lines[2] + " " + revision, re.I):
                        return False
        return True
    except (KeyError, TypeError, ValueError, IndexError, OverflowError):
        return False


class HowSureError(Exception):
    """Safe error code only; request URLs and response bodies are not printed."""

    def __init__(self, code: str):
        self.code = code
        super().__init__(code)


class InvalidArgumentError(HowSureError, ValueError):
    def __init__(self, code: str, *, field: str | None = None, message: str | None = None):
        super().__init__(code)
        self.message = message or code
        self.retryable = False
        self.hint = message
        self.details = [{"field": field, "code": "invalid_value", "message": self.message}] if field else []


class TransportError(HowSureError):
    pass


class ResponseValidationError(HowSureError):
    pass


class IdentityMismatchError(ResponseValidationError):
    pass


class HTTPResponseError(HowSureError):
    """HTTP status plus bounded public error fields; no raw response body.

    ``code`` and the exception's string retain the legacy ``http_N`` value.
    Inspect ``api_error``, ``message`` and ``details`` for the server's reason.
    """

    def __init__(self, status: int, retry_after: str | None = None, *, payload: object = None):
        self.status = status
        self.retry_after = retry_after
        super().__init__(f"http_{status}")
        failure = _api_failure(payload)
        self.api_error = failure.get("error")
        self.message = failure.get("message", self.code)
        self.retryable = failure.get("retryable")
        self.details = failure.get("details", [])
        self.hint = failure.get("hint")


class PartialResponseError(HTTPResponseError):
    """HTTP 503 updates with a validated partial body, available in ``data``."""

    def __init__(self, data: dict, retry_after: str | None = None):
        super().__init__(503, retry_after)
        self.data = data


def _require(ok: bool, code: str = "malformed_response") -> None:
    if not ok:
        raise ResponseValidationError(code)


def _identity(ok: bool) -> None:
    if not ok:
        raise IdentityMismatchError("identity_mismatch")


def _argument(ok: bool, code: str, *, field: str | None = None, message: str | None = None) -> None:
    if not ok:
        raise InvalidArgumentError(code, field=field, message=message)


def _text(value: object) -> bool:
    return isinstance(value, str) and len(value) <= MAX_BYTES


def _texts(value: object) -> bool:
    return isinstance(value, list) and len(value) <= 1000 and all(_text(item) for item in value)


def _integer(value: object, low: int, high: int) -> bool:
    return type(value) is int and low <= value <= high


def _time(value: object) -> bool:
    if not isinstance(value, str) or not re.fullmatch(r"[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\.[0-9]{1,9})?Z", value):
        return False
    try:
        datetime.fromisoformat(value.replace("Z", "+00:00"))
        return True
    except ValueError:
        return False


def _depth_decimal(value: object, places: int = 8, maximum: int = 1_000_000_000, zero: bool = False) -> Decimal | None:
    if not isinstance(value, str) or len(value) > 40 or not re.fullmatch(r"(?:0|[1-9]\d*)(?:\.\d{1," + str(places) + r"})?", value):
        return None
    result = Decimal(value)
    return result if (result >= 0 if zero else result > 0) and result <= maximum else None


def _validate_depth_estimate(value: dict) -> None:
    """Bind both gross-estimate versions to depth even when fees are unknown."""
    estimate = value["estimate"]
    _require(set(value["books"]) == {"YES", "NO"})
    if estimate["status"] == "unavailable":
        _require(estimate["below_minimum_order_size"] is None)
        return
    book = value["books"][estimate["outcome"]]
    with localcontext() as context:
        context.prec = 60
        requested = Decimal(estimate["requested_shares"])
        remaining, gross, consumed = requested, Decimal(0), []
        for level in book["asks" if estimate["side"] == "buy" else "bids"]:
            if remaining == 0:
                break
            price = Decimal(level["price"])
            size = min(remaining, Decimal(level["size"]))
            notional = price * size
            consumed.append((price, size, notional))
            remaining -= size
            gross += notional
        filled = requested - remaining
        _require(Decimal(estimate["filled_shares"]) == filled and Decimal(estimate["unfilled_shares"]) == remaining and Decimal(estimate["gross_notional"]) == gross)
        _require(len(estimate["consumed_levels"]) == len(consumed))
        for actual, expected in zip(estimate["consumed_levels"], consumed):
            _require(tuple(Decimal(actual[key]) for key in ("price", "size", "notional")) == expected)
        _require(estimate["vwap"] is None if filled == 0 else Decimal(estimate["vwap"]) == (gross / filled).quantize(Decimal("0.000000000001"), rounding=ROUND_HALF_UP))
        _require(estimate["worst_price"] is None if not consumed else Decimal(estimate["worst_price"]) == consumed[-1][0])
        minimum = book["min_order_size"]
        _require(estimate["below_minimum_order_size"] is None if minimum is None else estimate["below_minimum_order_size"] is (requested < Decimal(minimum)))


def _validate_purchase_cost(value: dict, include_proceeds: bool) -> None:
    """Validate evidence, exact selection and disclosed per-level fee arithmetic."""
    model, fees = value.get("fee_model"), value.get("fees")
    selling = include_proceeds and value["estimate"]["side"] == "sell"
    cost = value.get("sale_proceeds" if selling else "purchase_cost")
    total_key, requested_key = ("net_for_covered", "net_for_requested") if selling else ("total_for_covered", "total_for_requested")
    def unknown(entry, covered, requested):
        return isinstance(entry, dict) and entry.get("status") == "unknown" and all(key in entry and entry[key] is None for key in ("covered_shares", "gross_notional", "fee_amount", covered, requested, "unit")) and _text(entry.get("reason")) and bool(entry["reason"].strip())
    if include_proceeds:
        _require(unknown(value.get("purchase_cost"), "total_for_covered", "total_for_requested") if selling else unknown(value.get("sale_proceeds"), "net_for_covered", "net_for_requested"))
    _require(all(isinstance(item, dict) for item in (model, fees, cost)))
    _require(model.get("status") in ("verified", "unknown") and _time(model.get("checked_at")))
    instant = lambda stamp: datetime.fromisoformat(stamp.replace("Z", "+00:00"))
    checked, captured = instant(model["checked_at"]), instant(value["captured_at"])
    contract, books, estimate = value["contract"], value["books"], value["estimate"]
    _require(instant(contract["metadata_checked_at"]) <= checked <= captured)
    sources = model.get("sources")
    _require(isinstance(sources, list) and len(sources) <= 2)
    seen, source_times = set(), []
    source_urls = {"execution_version": "https://clob.polymarket.com/version",
                   "market_fee": "https://clob.polymarket.com/clob-markets/" + contract["condition_id"]}
    for source in sources:
        _require(isinstance(source, dict) and isinstance(source.get("kind"), str) and source["kind"] in source_urls and source["kind"] not in seen)
        _identity(source.get("source_url") == source_urls[source["kind"]])
        _require(_time(source.get("checked_at")) and isinstance(source.get("response_sha256"), str) and bool(re.fullmatch(r"[a-f0-9]{64}", source["response_sha256"])))
        stamp = instant(source["checked_at"])
        _require(instant(contract["metadata_checked_at"]) <= stamp <= checked)
        seen.add(source["kind"])
        source_times.append(stamp)
    if model["status"] == "unknown":
        _require(set(model) == {"status", "reason", "checked_at", "sources"} and _text(model.get("reason")) and bool(model["reason"].strip()))
    else:
        _require({"reason", "checked_at", "expires_at", "condition_id", "tokens", "book_hashes", "execution_version", "market_protocol", "neg_risk", "rate", "exponent", "taker_only", "collateral_asset", "rounding", "sources"} <= set(model))
        _require(model.get("reason") is None and seen == set(source_urls) and _time(model.get("expires_at")))
        _identity(model.get("condition_id") == contract["condition_id"] and model.get("tokens") == {"YES": contract["yes_token_id"], "NO": contract["no_token_id"]})
        _identity(model.get("book_hashes") == {outcome: books[outcome]["response_sha256"] for outcome in ("YES", "NO")})
        _require(any(book["status"] != "unavailable" for book in books.values()))
        _require(all(instant(book["captured_at"]) <= checked for book in books.values()))
        _require(type(model.get("execution_version")) is int and model["execution_version"] == 2 and model.get("market_protocol") == "ctf-v1" and type(model.get("neg_risk")) is bool)
        _require(_depth_decimal(model.get("rate"), maximum=1, zero=True) is not None and type(model.get("exponent")) is int and model["exponent"] in (1, 2))
        _require(model.get("taker_only") is True and model.get("collateral_asset") == "pUSD" and model.get("rounding") == "per_level_half_up_5dp")
        _require(instant(model["expires_at"]) == min(source_times) + timedelta(seconds=120))
        _require(checked <= instant(model["expires_at"]))
    _require({"status", "amount", "unit", "reason"} <= set(fees))
    cost_fields = {"covered_shares", "gross_notional", "fee_amount", total_key, requested_key, "unit"}
    _require(cost_fields | {"status", "reason"} <= set(cost))
    eligible = model["status"] == "verified" and (selling or estimate["side"] == "buy") and estimate["status"] != "unavailable" and Decimal(estimate["filled_shares"]) > 0 and captured <= instant(model["expires_at"])
    if fees["status"] == "unknown":
        _require(fees["status"] == "unknown" and fees["amount"] is None and fees["unit"] is None and _text(fees["reason"]) and bool(fees["reason"].strip()))
        _require(cost["status"] == "unknown" and all(cost[key] is None for key in cost_fields) and _text(cost["reason"]) and bool(cost["reason"].strip()))
        return
    _require(eligible)
    _require(fees["status"] == "estimated" and fees["unit"] == "pUSD" and fees["reason"] is None)
    _require(_depth_decimal(fees["amount"], places=5, maximum=1_000_000, zero=True) is not None)
    _require(cost["status"] == ("estimated" if estimate["status"] == "filled" else "partial") and cost["unit"] == "pUSD")
    _require(cost["reason"] is None if cost["status"] == "estimated" else _text(cost["reason"]) and bool(cost["reason"].strip()))
    _require(_depth_decimal(cost["covered_shares"], maximum=1_000_000) is not None and Decimal(cost["covered_shares"]) == Decimal(estimate["filled_shares"]))
    _require(_depth_decimal(cost["gross_notional"], places=16, maximum=1_000_000) is not None and Decimal(cost["gross_notional"]) == Decimal(estimate["gross_notional"]))
    _require(_depth_decimal(cost["fee_amount"], places=5, maximum=1_000_000, zero=True) is not None and Decimal(cost["fee_amount"]) == Decimal(fees["amount"]))
    _require(_depth_decimal(cost[total_key], places=16, maximum=2_000_000, zero=True) is not None)
    with localcontext() as context:
        context.prec = 80
        modeled = Decimal(0)
        for level in estimate["consumed_levels"]:
            price, size = Decimal(level["price"]), Decimal(level["size"])
            modeled += (size * Decimal(model["rate"]) * (price * (1 - price)) ** model["exponent"]).quantize(Decimal("0.00001"), rounding=ROUND_HALF_UP)
        total = Decimal(estimate["gross_notional"]) + (-modeled if selling else modeled)
        _require(Decimal(fees["amount"]) == modeled and Decimal(cost[total_key]) == total)
        if cost["status"] == "partial":
            _require(cost[requested_key] is None)
        else:
            _require(_depth_decimal(cost[requested_key], places=16, maximum=2_000_000, zero=True) is not None and Decimal(cost[requested_key]) == total)


_COMPARISON_RULE_LABELS = {
    "fed-meeting-rate-change": ["Rate and comparison", "YES condition", "NO condition", "Rounding", "No-statement exception", "Decision timing"],
    "us-gdp-growth": ["Metric and period", "YES condition", "NO condition", "Estimate vintage", "Shared boundary", "Scheduled release", "First delayed-release fallback", "Previous-figure fallback"],
    "fed-annual-rate-cuts": ["Counting unit and baseline", "YES condition", "NO condition", "Partial and nonstandard cuts", "Scheduled and emergency actions", "Annual window and cutoff", "Resolution sources and missing fallback", "What remains unknown"],
    "brazil-presidential-election": ["YES condition", "NO condition", "Election and timing", "Source hierarchy", "Unresolved-result fallback", "Pair completeness", "What remains unknown"],
    "us-house-control": ["YES condition", "NO condition", "Counting unit and window", "Seat attribution", "Independent members", "No-majority fallback", "Resolution sources", "Metadata and deadlines", "Pair completeness", "What remains unknown"],
}


def _validate_comparison_rules(comparison: dict) -> None:
    """Validate exact columns and literal statuses, without inferring meaning or authenticating sources."""
    def exact(value, keys):
        return isinstance(value, dict) and set(value) == set(keys)
    def retained(value, maximum=16_000):
        return isinstance(value, str) and 0 < len(value) <= maximum and bool(value.strip())
    instant = lambda value: datetime.fromisoformat(value.replace("Z", "+00:00"))
    reading, contracts = comparison["ruleReading"], comparison["contracts"]
    revision2 = isinstance(reading, dict) and type(reading.get("parserVersion")) is int and reading["parserVersion"] == 2
    _require(exact(reading, ("method", "status", "contracts", "rows", "limitations") + (("parserVersion",) if revision2 else ())))
    _require(reading["method"] == "complete_retained_terms" and isinstance(reading["contracts"], list) and len(reading["contracts"]) == len(contracts))
    _require(isinstance(reading["rows"], list) and len(reading["rows"]) <= (16 if revision2 else 8) and isinstance(reading["limitations"], list) and 1 <= len(reading["limitations"]) <= 20 and all(retained(item) for item in reading["limitations"]))
    for entry, contract in zip(reading["contracts"], contracts):
        _require(exact(entry, ("contractKey", "family", "status", "reason", "summary")))
        _identity(entry["contractKey"] == contract["key"])
        _require({"metadataObservedAt", "description", "resolutionRules", "resolutionSource", "resolutionSourceBasis"} <= set(contract))
        metadata_at = contract["metadataObservedAt"]
        _require(metadata_at is None or _time(metadata_at) and instant(metadata_at) <= instant(comparison["capturedAt"]))
        _require(all(contract[key] is None or retained(contract[key], limit) for key, limit in (("description", 64_000), ("resolutionRules", 64_000), ("resolutionSource", 16_000))))
        _require(contract["resolutionSourceBasis"] in (None, "market", "event", "series"))
        if entry["status"] == "recognized":
            _require(isinstance(entry["family"], str) and entry["family"] in _COMPARISON_RULE_LABELS and entry["reason"] is None and retained(entry["summary"]))
            _require(revision2 or entry["family"] in ("fed-meeting-rate-change", "us-gdp-growth"))
            house_source_gap = revision2 and entry["family"] == "us-house-control" and contract["resolutionSource"] is None and contract["resolutionSourceBasis"] in (None, "market")
            _require(contract["venue"] == "polymarket" and retained(contract["description"], 64_000) and
                     (house_source_gap or contract["resolutionSourceBasis"] == "market" and retained(contract["resolutionSource"])))
            _require(isinstance(contract.get("sourceUrl"), str) and bool(re.fullmatch(r"https://polymarket\.com/market/[a-z0-9][a-z0-9-]{0,179}", contract["sourceUrl"])))
        else:
            _require(entry["status"] == "unsupported" and entry["family"] is None and entry["summary"] is None and retained(entry["reason"]))
    recognized = [entry for entry in reading["contracts"] if entry["status"] == "recognized"]
    families = {entry["family"] for entry in recognized}
    expected = "unsupported" if not recognized else "different_families" if len(families) > 1 else "partial" if len(recognized) < len(contracts) else "recognized"
    _require(reading["status"] == expected)
    labels = _COMPARISON_RULE_LABELS[recognized[0]["family"]] if len(families) == 1 else []
    horizon_rows = 0
    if len(families) > 1 and reading["rows"]:
        _require(revision2 and len(contracts) == len(recognized) == 2 and families == {"fed-meeting-rate-change", "fed-annual-rate-cuts"})
        compatible = len(reading["rows"]) > 1 and isinstance(reading["rows"][1], dict) and reading["rows"][1].get("label") == "Compatible hypothetical scenario"
        horizon_rows = 2 if compatible else 1
        labels = ["Different horizons and metrics"] + (["Compatible hypothetical scenario"] if compatible else [])
        labels += [("Annual" if entry["family"] == "fed-annual-rate-cuts" else "Meeting") + " · " + label
                   for entry in reading["contracts"] for label in _COMPARISON_RULE_LABELS[entry["family"]]]
    _require(len(reading["rows"]) == len(labels))
    for index, (row, label) in enumerate(zip(reading["rows"], labels)):
        _require(exact(row, ("label", "status", "values")) and row["label"] == label and isinstance(row["values"], list) and len(row["values"]) == len(contracts))
        _require(all(value is None if entry["status"] == "unsupported" or horizon_rows and index >= horizon_rows and not
                     label.startswith(("Annual" if entry["family"] == "fed-annual-rate-cuts" else "Meeting") + " · ")
                     else retained(value) for entry, value in zip(reading["contracts"], row["values"])))
        expected = "not_comparable" if None in row["values"] else "same_reading" if len(set(row["values"])) == 1 else "different_reading"
        _require(row["status"] == expected)


def _market(value: object) -> bool:
    if not isinstance(value, str) or len(value) > 160:
        return False
    hip = _HIP.fullmatch(value)
    return bool(_POLY.fullmatch(value) or (hip and int(hip[1]) <= _HIP_MAX))


def _slug(value: str) -> str:
    if _POLY.fullmatch(value):
        return "polymarket-" + value.rsplit(":", 1)[1]
    return "hip4-" + value.rsplit(":", 1)[1]


def _cursor(value: object) -> bool:
    return isinstance(value, str) and bool(re.fullmatch(r"[1-9][0-9]{0,18}", value)) and int(value) <= 9_223_372_036_854_775_807


def _links(value: object, check_id: str) -> None:
    _require(isinstance(value, dict))
    base = "/api/free/v1/checks/" + check_id
    _identity(value.get("record") == base and value.get("updates") == base + "/updates" and value.get("page") == "/checks/" + check_id)


def _retry_after(value: object) -> str | None:
    if not isinstance(value, str) or len(value) > 128 or not all(32 <= ord(char) < 127 for char in value):
        return None
    if re.fullmatch(r"[0-9]{1,10}", value):
        return value
    try:
        return value if parsedate_to_datetime(value).tzinfo is not None else None
    except (ValueError, TypeError, OverflowError):
        return None


def _api_failure(value: object) -> dict:
    """Keep only the documented public error fields, never arbitrary JSON."""
    if not isinstance(value, dict):
        return {}
    if isinstance(value.get("data"), dict) and value["data"].get("ok") is False:
        value = value["data"]

    def safe_text(item: object, limit: int) -> bool:
        return isinstance(item, str) and 0 < len(item) <= limit and all(ord(char) >= 32 and ord(char) != 127 for char in item)

    if not safe_text(value.get("error"), 128) or not re.fullmatch(r"[A-Za-z0-9_:-]+", value["error"]):
        return {}
    result = {"error": value["error"]}
    for key in ("message", "hint"):
        if safe_text(value.get(key), 1000):
            result[key] = value[key]
    if type(value.get("retryable")) is bool:
        result["retryable"] = value["retryable"]
    details = value.get("details")
    if isinstance(details, list) and len(details) <= 20 and all(
        isinstance(item, dict) and safe_text(item.get("field"), 128) and safe_text(item.get("code"), 128) and safe_text(item.get("message"), 1000)
        for item in details
    ):
        result["details"] = [{key: item[key] for key in ("field", "code", "message")} for item in details]
    return result


def _polymarket_selection(value: object) -> tuple[str | None, str | None] | None:
    """Canonical IDs need a retained server mapping; native slugs do not."""
    if not isinstance(value, str):
        return None
    if _POLY.fullmatch(value):
        return value, None
    public = re.fullmatch(r"polymarket-([a-f0-9]{64})", value)
    if public:
        return "polymarket:condition-sha256:" + public[1], None
    if re.match(r"(?:polymarket|hip4)(?:-|:)", value, re.IGNORECASE):
        return None
    native = re.fullmatch(r"(?:https://polymarket\.com/market/)?([a-z0-9][a-z0-9-]{0,179})", value)
    if native:
        return None, native[1]
    return None


def _selected_polymarket_slug(value: dict, selected: tuple[str | None, str | None]) -> str:
    slug = value.get("market_slug")
    _require(isinstance(slug, str) and bool(re.fullmatch(r"[a-z0-9][a-z0-9-]{0,179}", slug)))
    market_id, native_slug = selected
    _identity(value.get("market_id") == market_id if market_id is not None else slug == native_slug)
    return slug


def _no_duplicates(pairs: list) -> dict:
    value = {}
    for key, item in pairs:
        if key in value:
            raise ValueError("duplicate_key")
        value[key] = item
    return value


def _bad_constant(_: str) -> None:
    raise ValueError("non_finite_json")


def _answer_correction(value):
    fields = {"id", "title", "publishedAt", "href", "scope", "before", "after", "action", "sourceUrl", "originalResponseSha256", "fixedRelease"}
    return (_only(value, fields) and all(isinstance(value.get(key), str) and value[key].strip() for key in fields)
            and _time(value["publishedAt"]) and re.fullmatch(r"/corrections/[a-z0-9][a-z0-9-]{0,159}", value["href"]) is not None
            and re.fullmatch(r"https://[^\s]+", value["sourceUrl"]) is not None
            and re.fullmatch(r"[a-f0-9]{64}", value["originalResponseSha256"]) is not None
            and re.fullmatch(r"[a-f0-9]{40}", value["fixedRelease"]) is not None)


def _answer_correction_review(value, document):
    if (not _only(value, {"schemaVersion", "registryVersion", "documentId", "versionId", "status", "findings", "limitations"})
            or type(value.get("schemaVersion")) is not int or value["schemaVersion"] != 1
            or not isinstance(value.get("registryVersion"), str) or re.fullmatch(r"\d{4}-\d{2}-\d{2}\.[1-9]\d{0,5}", value["registryVersion"]) is None
            or value.get("documentId") != document["documentId"] or value.get("versionId") != document["versions"][0]["id"]
            or not isinstance(value.get("findings"), list) or not isinstance(value.get("limitations"), list)
            or not value["limitations"] or not all(isinstance(row, str) and row.strip() for row in value["limitations"])):
        return False
    claims = document["versions"][0]["content"].get("claims")
    if not isinstance(claims, list) or len(value["findings"]) != len(claims):
        return False
    seen = set()
    for row in value["findings"]:
        if (not _only(row, {"claimId", "marketId", "status", "reason", "correction"})
                or not _agent_id(row.get("claimId")) or row["claimId"] in seen
                or not isinstance(row.get("marketId"), str) or not row["marketId"].strip()
                or not any(isinstance(claim, dict) and claim.get("id") == row["claimId"] and claim.get("marketId") == row.get("marketId") for claim in claims)
                or row.get("status") not in ("affected", "not_affected", "unknown")
                or not isinstance(row.get("reason"), str) or not row["reason"].strip()):
            return False
        seen.add(row["claimId"])
        notice = row.get("correction")
        if "correction" not in row or (row["status"] == "not_affected" and notice is not None) or (row["status"] == "affected" and not _answer_correction(notice)) or (row["status"] == "unknown" and notice is not None and not _answer_correction(notice)):
            return False
    status = "affected" if any(row["status"] == "affected" for row in value["findings"]) else "unknown" if not value["findings"] or any(row["status"] == "unknown" for row in value["findings"]) else "not_affected"
    return value.get("status") == status


def _shared_research_projection(version, access):
    if (not _only(access, {"grantId", "projectionSha256", "grantedAt", "expiresAt"}) or len(access) != 4
            or not isinstance(access.get("grantId"), str) or re.fullmatch(r"[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}", access["grantId"]) is None
            or not isinstance(access.get("projectionSha256"), str) or re.fullmatch(r"[a-f0-9]{64}", access["projectionSha256"]) is None
            or not _time(access.get("grantedAt")) or not _time(access.get("expiresAt")) or not _time(version.get("savedAt"))):
        return False
    parse = lambda value: datetime.fromisoformat(value.replace("Z", "+00:00"))
    if not parse(version["savedAt"]) <= parse(access["grantedAt"]) < parse(access["expiresAt"]) or (parse(access["expiresAt"]) - parse(access["grantedAt"])).total_seconds() > 90 * 86400:
        return False
    content = version.get("content")
    if (not _only(content, {"title", "summary", "context", "limitations", "claims"}) or len(content) != 5
            or content.get("summary") != "" or content.get("context") != "" or not isinstance(content.get("limitations"), str)
            or not content["limitations"].strip() or len(content["limitations"]) > 16000
            or not isinstance(content.get("claims"), list) or len(content["claims"]) != 1):
        return False
    claim = content["claims"][0]
    keys = {"id", "marketId", "question", "observedAt", "probability", "statement", "notes", "included", "category", "venue", "change24h", "liquidityUsd", "sourceUrl", "evidenceCapture"}
    if not _only(claim, keys) or set(claim) != keys or not _valid_capture(claim.get("evidenceCapture")):
        return False
    capture = claim["evidenceCapture"]
    number = lambda value: value is None or type(value) in (int, float) and math.isfinite(value)
    return (_agent_id(claim.get("id")) and claim["marketId"] == capture["marketId"] and claim["question"] == capture["contract"]["question"]
            and claim["sourceUrl"] == capture["venueUrl"] and content["title"] == capture["contract"]["question"][:500]
            and (claim["observedAt"] is None or _time(claim["observedAt"]))
            and number(claim["probability"]) and (claim["probability"] is None or 0 <= claim["probability"] <= 1)
            and isinstance(claim["statement"], str) and len(claim["statement"]) <= 16000 and claim["notes"] == "" and claim["included"] is True
            and isinstance(claim["category"], str) and len(claim["category"]) <= 128 and claim["venue"] == "polymarket"
            and number(claim["change24h"]) and number(claim["liquidityUsd"]) and (claim["liquidityUsd"] is None or claim["liquidityUsd"] >= 0)
            and parse(version["savedAt"]) >= parse(capture["capturedAt"]))


def _pce_watch_policy(policy, market_id):
    if not isinstance(policy, dict): return True
    context = policy.get("context")
    if policy.get("scope") != "pce_release" and (not isinstance(context, dict) or context.get("family") != "us-core-pce"): return True
    try:
        if set(policy) != {"schemaVersion", "identity", "scope", "context", "window"} or type(policy["schemaVersion"]) is not int or policy["schemaVersion"] != 1 or policy["scope"] != "pce_release": return False
        identity, context, window = policy["identity"], policy["context"], policy["window"]
        if set(identity) != {"marketId", "nativeMarketId", "conditionId", "nativeSlug", "venueUrl"} or identity["marketId"] != market_id or not _POLY.fullmatch(identity["marketId"]) or not re.fullmatch(r"[1-9]\d{0,99}", identity["nativeMarketId"]) or not re.fullmatch(r"0x[a-f0-9]{64}", identity["conditionId"]) or not re.fullmatch(r"[a-z0-9][a-z0-9-]{0,179}", identity["nativeSlug"]) or identity["venueUrl"] != "https://polymarket.com/market/" + identity["nativeSlug"]: return False
        if set(context) != {"family", "month", "year", "metric", "horizon", "seasonalAdjustment", "precisionDecimalPlaces", "valuePercent", "comparison", "expectedReleaseDate", "sourceVersion"}: return False
        number = context["valuePercent"]
        if context["family"] != "us-core-pce" or context["month"] not in _MACRO_MONTHS or not _integer(context["year"], 2000, 2099) or context["metric"] != "core_pce" or context["horizon"] != "one_month" or context["seasonalAdjustment"] != "seasonally_adjusted" or type(context["precisionDecimalPlaces"]) is not int or context["precisionDecimalPlaces"] != 1 or type(number) not in (int, float) or not math.isfinite(number) or abs(number) >= 1000 or number == 0 and math.copysign(1, number) < 0 or float(f"{number:.1f}") != number or context["comparison"] not in ("equal", "greater_than_or_equal") or context["comparison"] == "greater_than_or_equal" and number != .6 or context["sourceVersion"] != "retained_named_monthly_release": return False
        day = datetime.fromisoformat(context["expectedReleaseDate"] + "T00:00:00+00:00")
        following = datetime(context["year"] + (context["month"] == "December"), (_MACRO_MONTHS.index(context["month"]) + 1) % 12 + 1, 1, tzinfo=timezone.utc)
        stamp = lambda value: value.isoformat(timespec="milliseconds").replace("+00:00", "Z")
        return bool(re.fullmatch(r"20\d{2}-\d{2}-\d{2}", context["expectedReleaseDate"])) and day >= following and day.year <= context["year"] + 1 and set(window) == {"startAt", "expiresAt"} and window["startAt"] == stamp(day - timedelta(days=1)) and window["expiresAt"] == stamp(day + timedelta(days=6))
    except (TypeError, ValueError, KeyError, AttributeError): return False


def _pce_watch_snapshot(snapshot, capture):
    if not _valid_capture(capture) or not isinstance(snapshot, dict) or set(snapshot) != {"capturedAt", "metadataCapturedAt", "release", "sources"}: return False
    expected_sources = [{"id": row["id"], "url": row["url"], "locator": row["locator"], "checkedAt": row["checked_at"], "status": row["status"]} for row in capture["sources"]]
    if snapshot["capturedAt"] != capture["capturedAt"] or snapshot["metadataCapturedAt"] != capture["metadataCapturedAt"] or snapshot["sources"] != expected_sources: return False
    if snapshot["release"] is None:
        raw = {"contract": capture["contract"], "sources": capture["sources"], "identity": {"venueUrl": capture["venueUrl"], "capturedAt": capture["metadataCapturedAt"]}}
        return _macro_contract_context(raw, True) is None and _macro_contract_context(raw, False) is None
    release = snapshot["release"]
    if not isinstance(release, dict) or not {"status", "required", "observation", "conditionAssessment", "summary", "sourceIds", "limitations", "settlementEstablished"}.issubset(release) or set(release) - {"status", "required", "observation", "conditionAssessment", "summary", "sourceIds", "limitations", "settlementEstablished", "reportedValueComparison"}: return False
    pce = release["required"].get("metric") == "core_pce"
    raw = {"contract": capture["contract"], "sources": capture["sources"], "captured_at": capture["capturedAt"], "identity": {"venueUrl": capture["venueUrl"], "capturedAt": capture["metadataCapturedAt"]}, "collection_scope": "pce_release" if pce else "cpi_release", "contract_reading": {"family": "us-core-pce" if pce else "us-core-cpi", "pceRelease" if pce else "cpiRelease": release}}
    return _macro_release_response(raw)


def _pce_watch_facts(facts, comparison, market_id):
    if facts is None: return True
    if not isinstance(facts, dict): return False
    result = facts.get("comparison")
    if facts.get("kind") != "pce_release" and (not isinstance(result, dict) or result.get("family") != "us-core-pce"): return True
    try:
        if set(facts) != {"kind", "comparison"} or facts["kind"] != "pce_release" or not isinstance(comparison, dict): return False
        result, previous, current = facts["comparison"], comparison["previous"], comparison["current"]
        expected = {"schemaVersion", "family", "status", "observation", "reason", "summary", "previous", "current", "changedFields", "valueComparison", "provenance", "terms", "conditionAssessment", "settlementEstablished", "limitations"}
        if not isinstance(result, dict) or set(result) != expected or type(result["schemaVersion"]) is not int or result["schemaVersion"] != 1 or result["family"] != "us-core-pce" or result["settlementEstablished"] is not False or not _texts(result["limitations"]) or not result["limitations"] or not _text(result["summary"]): return False
        if result["status"] not in ("no_new_observation", "first_observed_release", "facts_changed", "provenance_changed", "facts_unchanged", "incomplete", "not_comparable") or result["observation"] not in ("new", "cached", "incompatible") or result["reason"] is not None and not _text(result["reason"]): return False
        if not _pce_watch_snapshot(result["previous"], previous) or not _pce_watch_snapshot(result["current"], current) or previous["marketId"] != market_id or current["marketId"] != market_id: return False
        fields = ("valuePercent", "headlineMonthlyPercent", "coreYearOverYearPercent", "headlineYearOverYearPercent")
        provenance_fields = ("sourceVersion", "url", "locator", "publishedAt", "revisionNotice", "annualUpdateNotice", "archiveNotice")
        term_fields = ("question", "description", "resolutionRules", "resolutionSource", "closesAt")
        if not isinstance(result["changedFields"], list) or len(set(result["changedFields"])) != len(result["changedFields"]) or any(field not in fields for field in result["changedFields"]): return False
        for key, allowed in (("provenance", provenance_fields), ("terms", term_fields)):
            row = result[key]
            if not isinstance(row, dict) or set(row) != {"status", "changedFields"} or row["status"] not in ("changed", "unchanged", "not_comparable") or not isinstance(row["changedFields"], list) or len(set(row["changedFields"])) != len(row["changedFields"]) or any(field not in allowed for field in row["changedFields"]): return False
        condition = result["conditionAssessment"]
        if set(condition) != {"status", "before", "after", "reason"} or condition["status"] != "not_comparable" or condition["before"] not in (None, "unknown") or condition["after"] not in (None, "unknown") or not _text(condition["reason"]): return False
        value = result["valueComparison"]
        if set(value) != {"status", "before", "after", "deltaPercentagePoints", "unit", "summary"} or value["status"] not in ("changed", "unchanged", "not_comparable") or value["unit"] != "percentage_points" or not _text(value["summary"]): return False
        if any(number is not None and (type(number) not in (int, float) or not math.isfinite(number)) for number in (value["before"], value["after"], value["deltaPercentagePoints"])): return False
        old = (result["previous"]["release"] or {}).get("observation"); new = (result["current"]["release"] or {}).get("observation")
        if value["before"] != (old or {}).get("valuePercent") or value["after"] != (new or {}).get("valuePercent"): return False
        changed_terms = [field for field in term_fields if previous["contract"].get(field) != current["contract"].get(field)]
        if result["terms"] != {"status": "changed" if changed_terms else "unchanged", "changedFields": changed_terms}: return False
        if value["status"] != "not_comparable":
            if not old or not new or value["before"] != old["valuePercent"] or value["after"] != new["valuePercent"] or value["deltaPercentagePoints"] != float(Decimal(str(value["after"])) - Decimal(str(value["before"]))) or value["status"] != ("unchanged" if value["before"] == value["after"] else "changed"): return False
        elif value["deltaPercentagePoints"] is not None: return False
        if result["status"] == "not_comparable": return result["observation"] == "incompatible" and result["changedFields"] == [] and value["status"] == "not_comparable" and result["provenance"] == {"status": "not_comparable", "changedFields": []}
        prior_monthly = next((source for source in previous["sources"] if source["id"] == "bea-pce-monthly-release"), None)
        next_monthly = next((source for source in current["sources"] if source["id"] == "bea-pce-monthly-release"), None)
        fresh = next_monthly is not None and (prior_monthly is None or next_monthly["checked_at"] > prior_monthly["checked_at"])
        if result["observation"] != ("new" if fresh else "cached"): return False
        if result["status"] == "no_new_observation" and (fresh or not old or not new): return False
        if old and new:
            def provenance(observation, snapshot):
                values = {field: observation.get(field) for field in provenance_fields}
                values["locator"] = next((source["locator"] for source in snapshot["sources"] if source["id"] == observation["sourceId"]), None)
                return values
            old_provenance, new_provenance = provenance(old, result["previous"]), provenance(new, result["current"])
            changed_provenance = [field for field in provenance_fields if old_provenance[field] != new_provenance[field]]
            if result["provenance"] != {"status": "changed" if changed_provenance else "unchanged", "changedFields": changed_provenance}: return False
        if result["status"] == "incomplete":
            release = result["current"]["release"]
            expected_reason = "release_pending" if release and release["status"] == "pending" else "current_release_unavailable" if not release or release["status"] != "observed" else "comparison_evidence_incomplete"
            if result["reason"] != expected_reason or expected_reason == "comparison_evidence_incomplete" and not any(source["status"] == "unavailable" for source in current["sources"]): return False
        if result["status"] in ("facts_changed", "facts_unchanged", "provenance_changed"):
            if not old or not new or result["observation"] != "new" or result["changedFields"] != [field for field in fields if old[field] != new[field]]: return False
            if result["status"] == "facts_changed" and not result["changedFields"] or result["status"] == "facts_unchanged" and (result["changedFields"] or result["provenance"]["status"] != "unchanged"): return False
        if result["status"] == "first_observed_release" and (old is not None or new is None or result["observation"] != "new"): return False
        return True
    except (TypeError, ValueError, KeyError, AttributeError): return False


def _pce_watch_update(row):
    if not isinstance(row, dict) or not _pce_watch_facts(row.get("factComparison"), row.get("comparison"), row.get("marketId")) or not _pce_watch_facts(row.get("transitionFactComparison"), row.get("transitionComparison"), row.get("marketId")): return False
    try:
        facts = row.get("factComparison")
        if not facts or facts.get("kind") != "pce_release": return row.get("status") != "pending"
        result = facts["comparison"]
        if result["status"] == "not_comparable": return row["status"] == "not_comparable"
        before = row["comparison"]["previous"]; after = row["comparison"]["current"]
        if result["status"] == "incomplete" and result["reason"] == "release_pending" and result["current"]["release"]["status"] == "pending" and after["status"] == "collected" and all(source["status"] == "collected" for source in after["sources"]):
            prior_index = next((source for source in before["sources"] if source["id"] == "bea-pce-release-index"), None)
            index = next((source for source in after["sources"] if source["id"] == "bea-pce-release-index"), None)
            fresh = index is not None and index["status"] == "collected" and _time(index["checked_at"]) and prior_index is not None and _time(prior_index["checked_at"]) and index["checked_at"] > prior_index["checked_at"]
            return row["status"] == ("pending" if fresh else "cached")
        if result["status"] == "incomplete": return row["status"] == "incomplete"
        if result["status"] in ("first_observed_release", "facts_changed", "provenance_changed") or result["terms"]["status"] == "changed": return row["status"] == "changed"
        if result["status"] == "no_new_observation": return row["status"] == "cached"
        return row["status"] in ("unchanged", "changed")
    except (TypeError, ValueError, KeyError, AttributeError): return False


def _shared_watch(watch, document):
    required = {"id", "documentId", "versionId", "claimId", "revision", "savedAt", "question", "marketId", "enabled", "startedAt", "expiresAt", "nextAttemptAt", "lastAttemptAt", "lastCaptureAt", "lastError", "baselineDigest"}
    if document.get("provenance") != "owner_shared_unverified" or not isinstance(watch, dict) or not required.issubset(watch) or set(watch) - required - {"policy", "attemptsRemaining", "stopReason"}: return False
    try:
        version = document["versions"][0]; claim = version["content"]["claims"][0]; capture = claim["evidenceCapture"]
        if not _valid_capture(capture) or not isinstance(watch["id"], str) or not re.fullmatch(r"[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}", watch["id"]): return False
        if any(watch[key] != value for key, value in {"documentId": document["documentId"], "versionId": version["id"], "claimId": claim["id"], "revision": version["revision"], "savedAt": version["savedAt"], "marketId": claim["marketId"], "question": claim["question"]}.items()): return False
        if type(watch["enabled"]) is not bool or not _time(watch["startedAt"]) or not _time(watch["expiresAt"]) or watch["expiresAt"] <= watch["startedAt"] or any(watch[key] is not None and not _time(watch[key]) for key in ("nextAttemptAt", "lastAttemptAt", "lastCaptureAt")): return False
        if any(watch.get(key) is not None and (not isinstance(watch[key], str) or not re.fullmatch(r"[a-z][a-z0-9_]{0,99}", watch[key])) for key in ("lastError", "stopReason")) or not isinstance(watch["baselineDigest"], str) or not re.fullmatch(r"[a-f0-9]{64}", watch["baselineDigest"]) or "attemptsRemaining" in watch and not _integer(watch["attemptsRemaining"], 0, 28): return False
        if "policy" not in watch: return "attemptsRemaining" not in watch
        policy = watch["policy"]
        if not isinstance(policy, dict) or set(policy) != {"schemaVersion", "identity", "scope", "context"} | ({"window"} if policy.get("scope") == "pce_release" else {"brackets"} if policy.get("scope") == "gdp_release_brackets" else set()) or type(policy["schemaVersion"]) is not int or policy["schemaVersion"] != 1 or policy["identity"] != {key: capture[key] for key in ("marketId", "nativeMarketId", "conditionId", "nativeSlug", "venueUrl")}: return False
        if policy["scope"] == "pce_release": return _pce_watch_policy(policy, claim["marketId"]) and watch["startedAt"] == policy["window"]["startAt"] and watch["expiresAt"] == policy["window"]["expiresAt"]
        context = policy["context"]
        if not isinstance(context, dict): return False
        if context.get("family") == "fed-meeting-rate-change":
            if policy["scope"] not in ("overview", "fed_decision") or set(context) != {"family", "meetingDate", "month", "year"}: return False
            date = datetime.fromisoformat(context["meetingDate"])
            return re.fullmatch(r"20\d{2}-\d{2}-\d{2}", context["meetingDate"]) is not None and type(context["year"]) is int and context["year"] == date.year and context["month"] == _MACRO_MONTHS[date.month-1]
        if policy["scope"] not in ("overview", "gdp_release", "gdp_release_brackets") or set(context) != {"family", "quarter", "year", "vintage", "expectedAdvanceDate"} or context["family"] != "us-gdp-growth" or not _integer(context["quarter"],1,4) or not _integer(context["year"],2000,2099) or context["vintage"] != "advance" or re.fullmatch(r"20\d{2}-\d{2}-\d{2}",context["expectedAdvanceDate"]) is None: return False
        datetime.fromisoformat(context["expectedAdvanceDate"])
        if policy["scope"] != "gdp_release_brackets": return True
        b = policy["brackets"]
        def valid_range(value):
            return isinstance(value,dict) and set(value) == {"lower","upper","threshold","tailDirection"} and all(value[key] is None or type(value[key]) in (int,float) and math.isfinite(value[key]) and abs(value[key]) < 1000 for key in ("lower","upper","threshold")) and value["tailDirection"] in (None,"less than","greater than")
        if not isinstance(b,dict) or set(b) != {"eventId","eventSlug","eventUrl","apiUrl","rangeFamily","contracts","selected"} or not re.fullmatch(r"[1-9]\d{0,99}",b["eventId"]) or not re.fullmatch(r"[a-z0-9][a-z0-9-]{0,179}",b["eventSlug"]) or b["eventUrl"] != "https://polymarket.com/event/"+b["eventSlug"] or b["apiUrl"] not in ("https://gamma-api.polymarket.com/events/"+b["eventId"],"https://gamma-api.polymarket.com/events/slug/"+b["eventSlug"]) or b["rangeFamily"] != "gdp_advance_contiguous_brackets" or not valid_range(b["selected"]) or not isinstance(b["contracts"],list) or not 3 <= len(b["contracts"]) <= 16: return False
        return all(isinstance(row,dict) and set(row) == {"nativeMarketId","conditionId","nativeSlug","lower","upper","threshold","tailDirection"} and re.fullmatch(r"[1-9]\d{0,99}",row["nativeMarketId"]) and re.fullmatch(r"0x[a-f0-9]{64}",row["conditionId"]) and re.fullmatch(r"[a-z0-9][a-z0-9-]{0,179}",row["nativeSlug"]) and valid_range({key:row[key] for key in ("lower","upper","threshold","tailDirection")}) for row in b["contracts"])
    except (TypeError, ValueError, KeyError, AttributeError, IndexError): return False


def _agent_id(value):
    return isinstance(value, str) and re.fullmatch(r"[A-Za-z0-9:_-]{1,120}", value) is not None


def _only(value, allowed):
    return isinstance(value, dict) and set(value).issubset(allowed)


def _version_href(value, document_id, version_id):
    if not isinstance(value, str) or not value.startswith("/") or value.startswith("//"):
        return False
    url = urlsplit(value)
    return not url.netloc and not url.fragment and url.path == "/research" and parse_qs(url.query) == {"researchDocument": [document_id], "version": [version_id]}


def _valid_capture(value):
    keys = {"schemaVersion", "marketId", "nativeMarketId", "conditionId", "nativeSlug", "venueUrl", "capturedAt", "metadataCapturedAt", "metadataSourceUrl", "metadataResponseSha256", "identityRecordSha256", "status", "contract", "sources", "gaps", "limitations", "relatedConditions"}
    if not isinstance(value, dict) or set(value) != keys or value.get("schemaVersion") != 1 or value.get("status") not in ("collected", "partial", "unsupported"):
        return False
    if not isinstance(value.get("marketId"), str) or not _POLY.fullmatch(value["marketId"]) or not isinstance(value.get("contract"), dict) or value["contract"].get("id") != value["marketId"]:
        return False
    if not _time(value.get("capturedAt")) or not _time(value.get("metadataCapturedAt")) or not all(isinstance(value.get(key), list) for key in ("sources", "gaps", "limitations", "relatedConditions")):
        return False
    try:
        return len(json.dumps(value, allow_nan=False).encode("utf-8")) <= 256 * 1024
    except (TypeError, ValueError):
        return False


def project_source_evidence_capture(evidence: dict) -> dict:
    """Local projection; the server validates complete capture semantics on save."""
    try:
        _argument(evidence.get("schema_version") == "howsure.evidence-request.v1" and evidence.get("meaning_verified") is False and evidence.get("check_published") is False, "invalid_argument", field="evidence")
        identity = evidence["identity"]
        reading = evidence.get("contract_reading") or {}
        value = {"schemaVersion": 1, "marketId": evidence["market_id"], "nativeMarketId": identity["identityRecord"]["id"], "conditionId": identity["identityRecord"]["conditionId"], "nativeSlug": evidence["market_slug"], "venueUrl": identity["venueUrl"], "capturedAt": evidence["captured_at"], "metadataCapturedAt": identity["capturedAt"], "metadataSourceUrl": identity["sourceUrl"], "metadataResponseSha256": identity["responseSha256"], "identityRecordSha256": identity["identityRecordSha256"], "status": evidence["status"], "contract": evidence["contract"], "sources": evidence["sources"], "gaps": evidence["gaps"], "limitations": evidence["limitations"], "relatedConditions": reading.get("conditions", []) if reading.get("method") == "deterministic_contract_rules" else []}
        _argument(_valid_capture(value) and identity.get("marketId") == value["marketId"] and identity["identityRecord"].get("slug") == value["nativeSlug"] and identity["identityRecord"].get("question") == value["contract"].get("question"), "invalid_argument", field="evidence")
        return json.loads(json.dumps(value))
    except (KeyError, TypeError, AttributeError):
        raise InvalidArgumentError("invalid_argument", field="evidence") from None


class HowSureClient:
    """Public reads and optional explicitly authorized private research operations.

    HTTPS origins only. HTTP loopback is available solely by explicit opt-in.
    Environment proxy settings are deliberately ignored. No cookie jar or
    redirects. Scoped credentials are restricted to private HowSure paths;
    writes require both explicit local opt-in and matching server scopes.
    """

    def __init__(self, origin: str = "https://howsure-web.vercel.app", *, timeout: float | None = None, allow_local_http: bool = False, agent_token: str | None = None, allow_agent_writes: bool = False):
        _argument(isinstance(origin, str) and not any(ord(char) <= 32 or ord(char) == 127 for char in origin), "invalid_origin")
        try:
            url = urlsplit(origin)
            port = url.port
            host = url.hostname
            local = allow_local_http is True and url.scheme == "http" and host in ("localhost", "127.0.0.1", "::1")
            valid = (url.scheme == "https" or local) and bool(host) and url.username is None and url.password is None and url.path in ("", "/") and not url.query and not url.fragment and "\\" not in origin
        except ValueError:
            raise InvalidArgumentError("invalid_origin") from None
        _argument(bool(valid), "invalid_origin")
        _argument(agent_token is None or isinstance(agent_token, str) and re.fullmatch(r"[A-Za-z0-9_.-]{20,512}", agent_token) is not None, "invalid_agent_token")
        _argument(type(allow_agent_writes) is bool, "invalid_argument")
        self.__agent_token, self.__agent_writes, self.__agent_local = agent_token, allow_agent_writes, local
        self._evidence_timeout = 30.0 if timeout is None else timeout
        self._book_timeout = 15.0 if timeout is None else timeout
        timeout = 10.0 if timeout is None else timeout
        _argument(type(timeout) in (int, float) and math.isfinite(timeout) and 0 < timeout <= 60, "invalid_timeout")
        self.origin = f"{url.scheme}://{url.netloc}"
        self.timeout = float(timeout)
        self._host, self._port, self._secure = host, port, url.scheme == "https"

    def _get(self, path: str, query: list | None = None, *, allow_partial: bool = False, request_timeout: float | None = None, _method: str = "GET", _body: bytes | None = None, _private: bool = False) -> tuple[int, str | None, dict]:
        if _private:
            _argument(self.__agent_token is not None and path.split("?", 1)[0].startswith("/api/agent/"), "invalid_argument")
            _argument(self.origin in _AGENT_ORIGINS or self.__agent_local, "untrusted_agent_origin")
            _argument(_method == "GET" or self.__agent_writes, "agent_writes_disabled")
        max_bytes = 4_000_000 if _private else MAX_BYTES
        target = path + ("?" + urlencode(query) if query else "")
        timeout = self.timeout if request_timeout is None else request_timeout
        deadline = time.monotonic() + timeout
        results: queue.Queue = queue.Queue(maxsize=1)
        holder: list = []

        def fetch() -> None:
            connection = None
            try:
                if self._secure:
                    connection = http.client.HTTPSConnection(self._host, self._port, timeout=timeout, context=ssl.create_default_context())
                else:
                    connection = http.client.HTTPConnection(self._host, self._port, timeout=timeout)
                holder.append(connection)
                connection.connect()
                remaining = deadline - time.monotonic()
                if remaining <= 0:
                    raise TransportError("timeout")
                if connection.sock is not None:
                    connection.sock.settimeout(remaining)
                headers = {"Accept": "application/json", "User-Agent": "howsure-python/" + __version__}
                if _private:
                    headers["Authorization"] = "Bearer " + self.__agent_token
                    if _body is not None:
                        headers["Content-Type"] = "application/json"
                connection.request(_method, target, body=_body, headers=headers)
                response = connection.getresponse()
                status, retry = response.status, _retry_after(response.getheader("Retry-After"))
                http_error = status != 200 and not (allow_partial and status == 503)
                try:
                    _require(response.getheader("Content-Type", "").split(";", 1)[0].strip().lower() == "application/json", "invalid_content_type")
                    length = response.getheader("Content-Length")
                    if length is not None:
                        _require(bool(re.fullmatch(r"[0-9]+", length)), "malformed_response")
                        _require(int(length) <= max_bytes, "response_too_large")
                    chunks, count = [], 0
                    while True:
                        remaining = deadline - time.monotonic()
                        if remaining <= 0:
                            raise TransportError("timeout")
                        if connection.sock is not None:
                            connection.sock.settimeout(remaining)
                        chunk = response.read1(min(65_536, max_bytes + 1 - count))
                        if not chunk:
                            break
                        count += len(chunk)
                        _require(count <= max_bytes, "response_too_large")
                        chunks.append(chunk)
                    try:
                        raw = b"".join(chunks)
                        if _private and self.__agent_token.encode() in raw:
                            raise TransportError("credential_in_response")
                        value = json.loads(raw.decode("utf-8"), object_pairs_hook=_no_duplicates, parse_constant=_bad_constant)
                    except (UnicodeDecodeError, ValueError, RecursionError):
                        raise ResponseValidationError("malformed_response") from None
                    _require(isinstance(value, dict))
                    if _private and self.__agent_token in json.dumps(value):
                        raise TransportError("credential_in_response")
                except ResponseValidationError:
                    if http_error:
                        raise HTTPResponseError(status, retry) from None
                    raise
                if http_error:
                    if _private:
                        code = value.get("error")
                        safe = {"error": code} if isinstance(code, str) and re.fullmatch(r"[a-z][a-z0-9_]{0,79}", code) else {}
                        scope = value.get("requiredScope")
                        if scope in ("research:read", "research:write", "watch:write"):
                            safe["hint"] = "This operation requires the " + scope + " scope."
                        field = value.get("field")
                        if isinstance(field, str) and re.fullmatch(r"[A-Za-z][A-Za-z0-9_.]{0,79}", field):
                            safe["details"] = [{"field": field, "code": safe.get("error", "request_rejected"), "message": "Correct the indicated field using the documented private API contract."}]
                        if code == "agent_updates_access_changed":
                            safe["hint"] = "Watch access changed. Keep processed receipt IDs, restart the feed explicitly without a cursor, and deduplicate by update ID. Do not retry the old cursor."
                        elif code == "agent_research_not_found":
                            safe["hint"] = "This exact research version is unavailable to this key. Ask the owner to check the chosen version and its active sharing grant; do not infer whether another document exists."
                        elif code == "invalid_agent_research" and field == "version":
                            safe["hint"] = "Provide the exact version ID returned by the research list or by the owner. Shared Check access never substitutes the latest version."
                        elif code == "research_watch_pce_disabled":
                            safe["hint"] = "Exact PCE watches are not enabled by the service; the saved version and explicit recheck remain available."
                        elif code == "research_watch_pce_limit":
                            safe["hint"] = "The one-target PCE pilot allowance is already allocated; disabling a watch does not reset it."
                        elif code == "research_watch_schedule":
                            safe["hint"] = "The exact release window is expired, too far away or inconsistent with its confirmed schedule. Keep the saved version and review its source date."
                        wait = value.get("retryAfterSeconds")
                        raise HTTPResponseError(status, str(wait) if type(wait) is int and 0 <= wait <= 86400 else None, payload=safe)
                    raise HTTPResponseError(status, retry, payload=value)
                results.put((status, retry, value))
            except HowSureError as error:
                results.put(error)
            except (TimeoutError, queue.Empty):
                results.put(TransportError("timeout"))
            except Exception:
                results.put(TransportError("request_failed"))
            finally:
                if connection is not None:
                    connection.close()

        # DNS and TLS setup can exceed a socket timeout. The caller deadline
        # also bounds these stages; the daemon never blocks interpreter exit.
        threading.Thread(target=fetch, daemon=True, name="howsure-read").start()
        try:
            result = results.get(timeout=max(0.001, deadline - time.monotonic()))
        except queue.Empty:
            if holder:
                try:
                    holder[0].close()
                except OSError:
                    pass
            raise TransportError("timeout") from None
        if isinstance(result, Exception):
            raise result from None
        return result

    def _agent(self, path: str, *, method: str = "GET", body: dict | None = None) -> dict:
        if self.__agent_token is None:
            raise InvalidArgumentError("agent_token_required")
        if self.origin not in _AGENT_ORIGINS and not self.__agent_local:
            raise InvalidArgumentError("untrusted_agent_origin")
        if method != "GET" and not self.__agent_writes:
            raise InvalidArgumentError("agent_writes_disabled")
        encoded = None if body is None else json.dumps(body, allow_nan=False, separators=(",", ":")).encode("utf-8")
        _argument(encoded is None or len(encoded) <= 300 * 1024, "input_too_large")
        if encoded is not None and self.__agent_token.encode() in encoded:
            raise InvalidArgumentError("credential_in_input")
        _, _, value = self._get(path, _method=method, _body=encoded, _private=True)
        return value

    def list_research(self) -> dict:
        """Agent-created versions and owner-selected shared versions; never other private browser notes."""
        value = self._agent("/api/agent/research?include_shared=true")
        _require(_only(value, {"documents", "limits"}) and isinstance(value.get("documents"), list) and isinstance(value.get("limits"), dict))
        for row in value["documents"]:
            _require(_only(row, {"documentId", "versionId", "claimId", "title", "marketId", "question", "savedAt", "revision", "href"}) and _agent_id(row.get("documentId")) and _agent_id(row.get("versionId")) and _time(row.get("savedAt")) and _version_href(row.get("href"), row.get("documentId"), row.get("versionId")))
        return value

    def read_research(self, document_id: str, *, version: str | None = None) -> dict:
        _argument(_agent_id(document_id) and (version is None or _agent_id(version)), "invalid_argument", field="documentId")
        value = self._agent("/api/agent/research/" + document_id + "?" + urlencode({**({"version": version} if version is not None else {}), "include_corrections": "true", "include_shared": "true", "include_watch": "true"}))
        _require(_only(value, {"documentId", "kind", "versions", "href", "provenance", "privateNotesIncluded", "correctionReview", "sharedAccess", "sharedWatch"}) and value.get("documentId") == document_id and value.get("kind") == "check" and value.get("provenance") in ("agent_supplied_unverified", "owner_shared_unverified") and value.get("privateNotesIncluded") is False and isinstance(value.get("versions"), list) and len(value["versions"]) == 1)
        for row in value["versions"]:
            _require(_only(row, {"id", "revision", "savedAt", "content"}) and _agent_id(row.get("id")) and _time(row.get("savedAt")) and isinstance(row.get("content"), dict))
        _require(_version_href(value.get("href"), document_id, value["versions"][0]["id"]))
        if value["provenance"] == "owner_shared_unverified":
            _require(version is not None and _shared_research_projection(value["versions"][0], value.get("sharedAccess")))
        else:
            _require("sharedAccess" not in value)
        _require("correctionReview" not in value or _answer_correction_review(value["correctionReview"], value))
        _require("sharedWatch" not in value or _shared_watch(value["sharedWatch"], value))
        if version is not None:
            _require(len(value["versions"]) == 1 and value["versions"][0]["id"] == version)
        return value

    def save_research(self, input: dict) -> dict:
        """Explicit immutable save, never a source fetch, semantic review or watch enable."""
        _argument(_only(input, {"idempotencyKey", "title", "summary", "capture", "evidence", "documentId", "expectedVersionId"}), "invalid_argument", field="input")
        _argument(isinstance(input.get("idempotencyKey"), str) and re.fullmatch(r"[A-Za-z0-9_-]{1,160}", input["idempotencyKey"]) is not None, "invalid_argument", field="idempotencyKey")
        _argument(isinstance(input.get("title"), str) and 0 < len(input["title"].strip()) <= 200 and len(input["title"]) <= 200, "invalid_argument", field="title")
        _argument("summary" not in input or isinstance(input["summary"], str) and len(input["summary"]) <= 4000, "invalid_argument", field="summary")
        _argument(("capture" in input) != ("evidence" in input), "invalid_argument", field="capture")
        _argument("documentId" not in input and "expectedVersionId" not in input or _agent_id(input.get("documentId")) and _agent_id(input.get("expectedVersionId")), "invalid_argument", field="documentId")
        body = dict(input)
        if "evidence" in body:
            body["capture"] = project_source_evidence_capture(body.pop("evidence"))
        _argument(_valid_capture(body["capture"]), "invalid_argument", field="capture")
        value = self._agent("/api/agent/research", method="POST", body=body)
        _require(_only(value, {"documentId", "versionId", "claimId", "savedAt", "revision", "href", "replayed"}) and all(_agent_id(value.get(key)) for key in ("documentId", "versionId", "claimId")) and _time(value.get("savedAt")) and _version_href(value.get("href"), value.get("documentId"), value.get("versionId")) and type(value.get("replayed")) is bool)
        return value

    def set_research_watch(self, *, document_id: str, version_id: str, claim_id: str, enabled: bool) -> dict:
        _argument(all(_agent_id(value) for value in (document_id, version_id, claim_id)) and type(enabled) is bool, "invalid_argument", field="watch")
        value = self._agent("/api/agent/watches", method="PUT", body={"documentId": document_id, "versionId": version_id, "claimId": claim_id, "enabled": enabled})
        _require(_only(value, {"watches", "limits", "serviceStatus"}) and isinstance(value.get("watches"), list) and all(isinstance(row, dict) and _pce_watch_policy(row.get("policy"), row.get("marketId")) for row in value["watches"]) and isinstance(value.get("limits"), dict) and isinstance(value.get("serviceStatus"), str))
        return value

    def read_research_updates(self, *, cursor: str | None = None, limit: int = 10) -> dict:
        """Persist returned cursor; an empty feed does not establish unchanged sources."""
        _argument(cursor is None or isinstance(cursor, str) and re.fullmatch(r"[A-Za-z0-9_.-]{1,2048}", cursor) is not None, "invalid_argument", field="cursor")
        _argument(_integer(limit, 1, 20), "invalid_argument", field="limit")
        query = {"limit": str(limit)}
        if cursor is not None:
            query["cursor"] = cursor
        value = self._agent("/api/agent/updates?" + urlencode(query))
        _require(_only(value, {"updates", "nextCursor", "hasMore", "coverage", "checkedAt"}) and isinstance(value.get("updates"), list) and all(_pce_watch_update(row) for row in value["updates"]) and type(value.get("hasMore")) is bool and _time(value.get("checkedAt")))
        _require(value.get("nextCursor") is None or isinstance(value["nextCursor"], str) and re.fullmatch(r"[A-Za-z0-9_.-]{1,2048}", value["nextCursor"]) is not None)
        coverage = value.get("coverage")
        _require(isinstance(coverage, dict) and coverage.get("retainedOnly") is True and _integer(coverage.get("updatesOmitted"), 0, 1_000_000) and _texts(coverage.get("limitations")))
        return value

    def capabilities(self) -> dict:
        """Static product support, never proof of live coverage or freshness."""
        _, _, value = self._get("/api/free/v1/capabilities")
        _require(value.get("schema_version") == "howsure.capabilities.v1" and value.get("scope") == "published_product_contract" and value.get("runtime_status") == "not_checked")
        _require(value.get("readiness_url") == "/api/health/howsure" and isinstance(value.get("authority"), dict))
        authority = value["authority"]
        _require(authority.get("read_only") is True and all(authority.get(key) is False for key in ("orders", "trading", "wallet_signing")))
        venues = value.get("venues")
        _require(isinstance(venues, list) and len(venues) <= 20 and all(isinstance(venue, dict) for venue in venues))
        ids = [venue.get("id") for venue in venues]
        _require(all(item in ("polymarket", "hip4", "kalshi") for item in ids) and len(set(ids)) == len(ids))
        for venue in venues:
            _require(_text(venue.get("label")) and venue.get("integration_status") in ("supported", "offline_only") and _texts(venue.get("limitations")))
            for key in ("public_api", "collection"):
                _require(isinstance(venue.get(key), dict) and all(type(item) is bool for item in venue[key].values()))
        _require(isinstance(value.get("operations"), list) and _texts(value.get("limitations")))
        for operation in value["operations"]:
            _require(isinstance(operation, dict) and _text(operation.get("id")) and operation.get("method") == "GET" and isinstance(operation.get("path"), str) and operation["path"].startswith("/api/") and _texts(operation.get("venues")))
        return value

    @staticmethod
    def _envelope(value: dict, path: str) -> dict:
        _require(value.get("schema_version") == "howsure.free-api.v1" and _time(value.get("fetched_at")) and value.get("not_trade_advice") is True)
        _identity(value.get("endpoint") == path)
        meta = value.get("meta")
        _require(isinstance(meta, dict) and meta.get("source_status") in ("healthy", "degraded", "unavailable", "unknown") and type(meta.get("partial")) is bool and _texts(meta.get("warnings")) and _texts(meta.get("degraded_sources")))
        _require(isinstance(value.get("data"), dict) and value["data"].get("ok") is not False)
        return value["data"]

    @staticmethod
    def _market_row(row: object) -> None:
        _require(isinstance(row, dict) and _market(row.get("id")) and _text(row.get("question")) and _texts(row.get("missing_fields")))
        _identity(row.get("slug") == _slug(row["id"]))
        source = row.get("source")
        _require(isinstance(source, dict) and source.get("status") in ("fresh", "stale", "unknown"))
        _identity(source.get("venue") == ("polymarket" if _POLY.fullmatch(row["id"]) else "hip4"))
        for key in ("observed_at", "valid_until"):
            _require(source.get(key) is None or _time(source[key]))
        _require("probability" in row and (row["probability"] is None or type(row["probability"]) in (int, float) and math.isfinite(row["probability"]) and 0 <= row["probability"] <= 1))
        _require(row["probability"] is None or _time(source.get("observed_at")))

    def search_markets(self, *, q: str = "", category: str = "", limit: int = 20, offset: int = 0, generation: str | None = None) -> dict:
        _argument(isinstance(q, str) and len(q.strip()) <= 200, "invalid_query", field="q", message="Use a text query of at most 200 characters after trimming.")
        _argument(isinstance(category, str) and len(category.strip()) <= 80, "invalid_query", field="category", message="Use a category string of at most 80 characters after trimming.")
        _argument(_integer(limit, 1, 100), "invalid_pagination", field="limit", message="Use an integer limit from 1 to 100.")
        _argument(_integer(offset, 0, 10_000), "invalid_pagination", field="offset", message="Use an integer offset from 0 to 10000.")
        _argument(generation is None or isinstance(generation, str) and bool(_GENERATION.fullmatch(generation)), "invalid_generation", field="generation", message="Use the returned sha256: generation token with 64 lowercase hexadecimal characters, or omit it for the first page.")
        q, category = q.strip(), category.strip()
        parameters = [("q", q), ("category", category), ("limit", limit), ("offset", offset)]
        if generation is not None:
            parameters.append(("generation", generation))
        path = "/api/free/v1/markets/search"
        _, _, value = self._get(path, parameters)
        data = self._envelope(value, path)
        rows, pagination = data.get("results"), data.get("pagination")
        _require(isinstance(rows, list) and len(rows) <= limit and _integer(data.get("returned"), 0, limit) and data["returned"] == len(rows) and _integer(data.get("total_matches"), 0, 10_000_000))
        _identity(data.get("query") == (q or None) and data.get("filters") == {"category": category or None, "limit": limit, "offset": offset})
        _require("generation" in data and (data["generation"] is None or isinstance(data["generation"], str) and bool(_GENERATION.fullmatch(data["generation"]))))
        if generation is not None:
            _identity(data["generation"] == generation)
        _require(isinstance(pagination, dict) and type(pagination.get("has_more")) is bool)
        _identity(pagination.get("limit") == limit and pagination.get("offset") == offset)
        scope = data.get("scope")
        _require(isinstance(scope, dict) and type(scope.get("truncated")) is bool)
        expected_returned = min(limit, max(0, data["total_matches"] - offset))
        has_more = offset + expected_returned < data["total_matches"]
        next_offset = offset + limit if has_more and offset + limit <= 10_000 else None
        _require(len(rows) == expected_returned and pagination["has_more"] is has_more)
        _require("next_offset" in pagination and (pagination["next_offset"] is None if next_offset is None else
                 _integer(pagination["next_offset"], 1, 10_000) and pagination["next_offset"] == next_offset))
        _require(scope["truncated"] is (has_more and next_offset is None))
        for row in rows:
            self._market_row(row)
        _require(len({row["id"] for row in rows}) == len(rows))
        return value

    def list_checks(self, market_id: str | None = None) -> dict:
        _argument(market_id is None or _market(market_id), "invalid_market_id", field="market_id", message="Use an exact canonical Polymarket or supported HIP-4 market ID returned by search, or omit market_id for all published Checks.")
        _, _, value = self._get("/api/free/v1/checks", [("market_id", market_id)] if market_id else None)
        _require(value.get("schema_version") == "howsure.check-index.v1" and isinstance(value.get("checks"), list) and _integer(value.get("count"), 0, 1000) and value["count"] == len(value["checks"]))
        _identity(value.get("market_id") == market_id)
        seen = set()
        for row in value["checks"]:
            _require(isinstance(row, dict) and isinstance(row.get("id"), str) and bool(_CHECK_ID.fullmatch(row["id"])) and row["id"] not in seen and _market(row.get("market_id")) and _time(row.get("reviewed_at")))
            seen.add(row["id"])
            _identity(market_id is None or row["market_id"] == market_id)
            _links(row.get("links"), row["id"])
        return value

    def read_check(self, check_id: str) -> dict:
        _argument(isinstance(check_id, str) and bool(_CHECK_ID.fullmatch(check_id)), "invalid_check_id", field="check_id", message="Use an exact Check ID returned by list_checks: 1 to 160 lowercase letters, digits or hyphens, starting with a letter or digit.")
        _, _, value = self._get("/api/free/v1/checks/" + check_id)
        _require(value.get("schema_version") == "howsure.check.v1" and isinstance(value.get("check"), dict))
        check = value["check"]
        _identity(check.get("id") == check_id)
        _require(_integer(check.get("schemaVersion"), 1, 1) and _market(check.get("marketId")) and _time(check.get("reviewedAt")) and check.get("reviewMethod") == "source_review")
        _require(all(_text(check.get(key)) for key in ("marketQuestion", "title", "conclusion")) and all(_texts(check.get(key)) for key in ("limitations", "nextChecks")))
        _require(isinstance(check.get("capturedMarket"), dict) and isinstance(check.get("sources"), list) and bool(check["sources"]) and isinstance(check.get("claims"), list) and isinstance(check.get("conditions"), list))
        _require(isinstance(value.get("identity"), dict) and value["identity"].get("status") in ("verified", "unknown") and value["identity"].get("current_freshness") == "not_established")
        _identity(value["identity"].get("market_id") == check["marketId"])
        _links(value.get("links"), check_id)
        _require(_texts(value.get("limitations")))
        return value

    def read_updates(self, check_id: str) -> dict:
        _argument(isinstance(check_id, str) and bool(_CHECK_ID.fullmatch(check_id)), "invalid_check_id", field="check_id", message="Use an exact Check ID returned by list_checks: 1 to 160 lowercase letters, digits or hyphens, starting with a letter or digit.")
        status, retry, value = self._get("/api/free/v1/checks/" + check_id + "/updates", allow_partial=True)
        if status == 503 and value.get("schema_version") != "howsure.check-updates.v1":
            raise HTTPResponseError(503, retry, payload=value)
        _require(value.get("schema_version") == "howsure.check-updates.v1" and _time(value.get("checked_at")))
        _identity(value.get("check_id") == check_id)
        _links(value.get("links"), check_id)
        _require(isinstance(value.get("identity"), dict) and _market(value["identity"].get("market_id")))
        publication, contract, monitoring = value.get("publication"), value.get("contract"), value.get("source_monitoring")
        _require(isinstance(publication, dict) and type(publication.get("newer_version_available")) is bool and isinstance(publication.get("versions"), list))
        _require(publication.get("latest_check_id") is None or isinstance(publication["latest_check_id"], str) and bool(_CHECK_ID.fullmatch(publication["latest_check_id"])))
        for row in publication["versions"]:
            _require(isinstance(row, dict) and isinstance(row.get("id"), str) and bool(_CHECK_ID.fullmatch(row["id"])) and _time(row.get("reviewed_at")))
            _links(row.get("links"), row["id"])
        _require(isinstance(contract, dict) and contract.get("status") in ("matches_recorded_context", "context_changed", "identity_mismatch", "predates_review", "stale", "unknown", "unavailable", "not_found") and _texts(contract.get("changed_fields")) and isinstance(contract.get("captures"), dict))
        _require(isinstance(monitoring, dict) and monitoring.get("status") in ("recorded", "partial", "not_monitored", "unknown", "unavailable") and monitoring.get("publication_status") in ("available", "archive_fallback", "unavailable", "not_found") and monitoring.get("current_source_freshness") == "not_established" and monitoring.get("scope") == "bounded_named_passage_only")
        _require(isinstance(value.get("changes"), dict) and _texts(value.get("limitations")))
        if status == 503:
            raise PartialResponseError(value, retry)
        return value

    def read_conditions(self, market_id: str, *, before: str | None = None, limit: int = 10) -> dict:
        _argument(isinstance(market_id, str) and bool(_POLY.fullmatch(market_id)), "invalid_market_id", field="market_id", message="Use the exact polymarket:condition-sha256: ID with 64 lowercase hexadecimal characters returned by search; HIP-4 conditions are unsupported.")
        _argument(before is None or _cursor(before), "invalid_cursor", field="before", message="Use the returned nextCursor as a positive decimal string up to 9223372036854775807, or omit before for the first page.")
        _argument(_integer(limit, 1, 20), "invalid_limit", field="limit", message="Use an integer limit from 1 to 20.")
        parameters = [("limit", limit)] + ([("before", before)] if before else [])
        _, _, value = self._get("/api/free/v1/markets/" + market_id + "/conditions", parameters)
        _require(value.get("schemaVersion") == "howsure.condition-history.v1" and _time(value.get("readAt")) and value.get("timestampBasis") == "catalog_observation" and value.get("historyScope") == "accepted_product_snapshots")
        _identity(value.get("marketId") == market_id)
        rows = value.get("revisions")
        _require(isinstance(rows, list) and len(rows) <= limit and value.get("status") == ("available" if rows else "not_retained"))
        previous = int(before) if before else 9_223_372_036_854_775_808
        for row in rows:
            _require(isinstance(row, dict) and _cursor(row.get("id")) and int(row["id"]) < previous and _time(row.get("observedAt")) and _time(row.get("recordedAt")) and isinstance(row.get("fields"), dict) and isinstance(row.get("changes"), list))
            _identity(row.get("marketId") == market_id)
            previous = int(row["id"])
        _require(value.get("nextCursor") is None or bool(rows) and value["nextCursor"] == rows[-1]["id"])
        return value

    def read_snapshot(self, slug: str) -> dict:
        _argument(isinstance(slug, str), "invalid_market_slug", field="slug", message="Use the exact public polymarket-<64 lowercase hex> or supported hip4-<outcome number> slug returned by search, not a canonical ID or venue URL.")
        market_id = "polymarket:condition-sha256:" + slug[11:] if slug.startswith("polymarket-") else "hip4:mainnet:outcome:" + slug[5:] if slug.startswith("hip4-") else ""
        _argument(_market(market_id) and _slug(market_id) == slug, "invalid_market_slug", field="slug", message="Use the exact public polymarket-<64 lowercase hex> or supported hip4-<outcome number> slug returned by search, not a canonical ID or venue URL.")
        path = "/api/free/v1/markets/" + slug + "/snapshot-lite"
        _, _, value = self._get(path)
        data = self._envelope(value, path)
        self._market_row(data.get("market"))
        _identity(data["market"]["id"] == market_id and data["market"]["slug"] == slug)
        return value

    def collect_source_evidence(self, market: str, *, include_decision: bool = False, include_release: bool = False, include_brackets: bool = False, include_pce_release: bool = False, include_cpi_release: bool = False) -> dict:
        """Exact native slug/URL or retained canonical ID; never verified truth.

        Canonical IDs and HowSure public slugs require an active/archive mapping
        and matching live condition identity on the server. Mapping may be absent.
        """
        selected = _polymarket_selection(market)
        _argument(selected is not None, "invalid_market_selection", field="market", message="Use an exact native Polymarket slug/market URL or retained HowSure canonical ID/public slug; event URLs and HIP-4 are unsupported.")
        _argument(type(include_decision) is bool, "invalid_argument", field="include_decision", message="Use True for one explicit Fed decision-source read or False for the standard source capture.")
        _argument(type(include_release) is bool, "invalid_argument", field="include_release", message="Use True for one explicit GDP advance-release read or False for the standard source capture.")
        _argument(type(include_brackets) is bool, "invalid_argument", field="include_brackets", message="Use True for the exact GDP event bracket roster or False to keep the release-only read.")
        _argument(not include_brackets or include_release and not include_decision, "invalid_argument", field="include_brackets", message="include_brackets requires include_release=True and excludes include_decision=True.")
        _argument(type(include_pce_release) is bool, "invalid_argument", field="include_pce_release", message="Use True for one explicit named PCE monthly-release read.")
        _argument(type(include_cpi_release) is bool, "invalid_argument", field="include_cpi_release", message="Use True for one explicit named CPI release read.")
        _argument(sum((include_decision, include_release, include_pce_release, include_cpi_release)) <= 1, "invalid_argument", field="include_release", message="Choose one optional source scope: include_decision, include_release, include_pce_release or include_cpi_release.")
        instant = lambda value: datetime.fromisoformat(value.replace("Z", "+00:00"))
        query = [("market", market)]
        if include_decision:
            query.append(("include_decision", "true"))
        if include_release:
            query.append(("include_release", "true"))
        if include_brackets:
            query.append(("include_brackets", "true"))
        if include_pce_release:
            query.append(("include_pce_release", "true"))
        if include_cpi_release:
            query.append(("include_cpi_release", "true"))
        _, _, value = self._get("/api/free/v1/research/evidence", query, request_timeout=self._evidence_timeout)
        _require(value.get("collection_scope") == "pce_release" if include_pce_release else value.get("collection_scope") == "cpi_release" if include_cpi_release else value.get("collection_scope") == "fed_decision" if include_decision else value.get("collection_scope") == "gdp_release_brackets" if include_brackets else value.get("collection_scope") == "gdp_release" if include_release else "collection_scope" not in value)
        _require(value.get("schema_version") == "howsure.evidence-request.v1" and value.get("status") in ("collected", "partial", "unsupported") and _time(value.get("captured_at")))
        _require(value.get("meaning_verified") is False and value.get("check_published") is False and _texts(value.get("gaps")) and _texts(value.get("limitations")))
        market_id, identity, contract = value.get("market_id"), value.get("identity"), value.get("contract")
        _require(isinstance(market_id, str) and bool(_POLY.fullmatch(market_id)) and isinstance(identity, dict) and isinstance(contract, dict))
        slug = _selected_polymarket_slug(value, selected)
        native = identity.get("identityRecord")
        _require(isinstance(native, dict) and _time(identity.get("capturedAt")) and instant(identity["capturedAt"]) <= instant(value["captured_at"]))
        _require(isinstance(native.get("conditionId"), str) and bool(re.fullmatch(r"0x[a-f0-9]{64}", native["conditionId"])) and isinstance(native.get("id"), str) and bool(re.fullmatch(r"[1-9]\d{0,99}", native["id"])))
        _identity(market_id == "polymarket:condition-sha256:" + hashlib.sha256(("orrery-polymarket-canonical-identity.v1\0condition_id\0" + native["conditionId"]).encode()).hexdigest())
        _identity(value.get("market_slug") == slug and identity.get("marketId") == market_id and native.get("slug") == slug and identity.get("venueUrl") == "https://polymarket.com/market/" + slug)
        _identity(contract.get("id") == market_id and contract.get("slug") == _slug(market_id) and contract.get("venue") == "polymarket" and native.get("question") == contract.get("question"))
        _require(isinstance(contract.get("question"), str) and bool(contract["question"].strip()))
        sources = value.get("sources")
        _require(isinstance(sources, list) and len(sources) <= (6 if include_brackets else 5 if include_release else 3 if include_cpi_release else 4 if include_decision or include_pce_release else 2))
        ids = []
        for source in sources:
            _require(isinstance(source, dict) and all(_text(source.get(key)) for key in ("id", "title", "publisher", "url")) and source["url"].startswith("https://") and _time(source.get("checked_at")) and instant(source["checked_at"]) <= instant(value["captured_at"]))
            _require(source.get("status") in ("collected", "unavailable") and (source.get("reason") is None or _text(source["reason"])))
            _require(_text(source.get("excerpt")) and bool(source["excerpt"].strip()) and _text(source.get("locator")) if source["status"] == "collected" else source.get("excerpt") is None and source.get("locator") is None)
            ids.append(source["id"])
        _require(len(set(ids)) == len(ids))
        _require(not any(source["id"] == "polymarket-gdp-event-brackets" and not include_brackets or source["id"] == "bea-gdp-revision-release" and not include_release for source in sources))
        _require(_fed_calendar_response(value) and _decision_response(value) and _release_response(value) and _macro_release_response(value))
        bundle = value.get("evidence_bundle")
        if value["status"] == "collected":
            _require(not value["gaps"] and len(sources) >= 2 and all(source["status"] == "collected" for source in sources) and isinstance(bundle, dict))
            _require(isinstance(bundle.get("market"), dict) and isinstance(bundle.get("identityEvidence"), list) and len(bundle["identityEvidence"]) == 1 and isinstance(bundle["identityEvidence"][0], dict) and isinstance(bundle.get("sources"), list) and len(bundle["sources"]) == len(sources))
            _identity(bundle["market"].get("id") == market_id and bundle["market"].get("question") == contract["question"] and bundle["identityEvidence"][0].get("marketId") == market_id)
            _identity(bundle["market"] == contract and bundle["identityEvidence"][0] == identity)
            source_ids = []
            for retained in bundle["sources"]:
                _require(isinstance(retained, dict))
                displayed = next((item for item in sources if item["id"] == retained.get("id")), None)
                _identity(displayed is not None and all(retained.get(key) == displayed[key] for key in ("title", "url", "publisher", "excerpt", "locator")) and retained.get("accessedAt") == displayed["checked_at"])
                source_ids.append(retained["id"])
            _require(len(set(source_ids)) == len(source_ids))
        else:
            _require(bool(value["gaps"]) and bundle is None)
        return value

    def read_order_book(self, market: str, *, quantity: str = "100", outcome: str = "YES", side: str = "buy", include_cost: bool = True, include_proceeds: bool | None = None) -> dict:
        """One GET for a native slug/URL or retained canonical ID, never an order.

        Canonical IDs/public slugs require a retained server mapping and matching
        live condition. The default v2 receipt includes fee evidence and a bounded
        purchase-cost and sale-proceeds models; unknown fees remain unknown, never zero. Explicit
        include_cost=False requests the v1 gross-only receipt. No HIP4 support.
        """
        selected = _polymarket_selection(market)
        requested = _depth_decimal(quantity, maximum=1_000_000)
        _argument(selected is not None, "invalid_book_selection", field="market", message="Use an exact native Polymarket slug/market URL or retained HowSure canonical ID/public slug; event URLs and HIP-4 are unsupported.")
        _argument(requested is not None, "invalid_book_selection", field="quantity", message="Use a positive decimal string up to 1000000 shares with at most 8 decimal places.")
        _argument(outcome in ("YES", "NO"), "invalid_book_selection", field="outcome", message="Use exactly YES or NO.")
        _argument(side in ("buy", "sell"), "invalid_book_selection", field="side", message="Use exactly buy or sell.")
        _argument(type(include_cost) is bool, "invalid_book_selection", field="include_cost", message="Use True for the purchase-cost receipt or False for the legacy gross-only receipt.")
        include_proceeds = include_cost if include_proceeds is None else include_proceeds
        _argument(type(include_proceeds) is bool and (not include_proceeds or include_cost), "invalid_book_selection", field="include_proceeds", message="Use True with include_cost=True for sale proceeds, or False for the previous receipt.")
        query = [("market", market), ("quantity", quantity), ("outcome", outcome), ("side", side)]
        if include_proceeds:
            query.append(("include_proceeds", "true"))
        if include_cost:
            query.append(("include_cost", "true"))
        _, _, value = self._get("/api/free/v1/contracts/order-book", query, request_timeout=self._book_timeout)
        _require(value.get("schema_version") == ("howsure.order-book.v2" if include_cost else "howsure.order-book.v1") and value.get("status") in ("collected", "partial", "unavailable") and _time(value.get("captured_at")))
        _require(value.get("quote_unit") == "collateral_units" and value.get("share_unit") == "outcome_shares" and _texts(value.get("limitations")))
        market_id, contract, books, estimate, fees = (value.get(key) for key in ("market_id", "contract", "books", "estimate", "fees"))
        _require(isinstance(market_id, str) and bool(_POLY.fullmatch(market_id)) and all(isinstance(item, dict) for item in (contract, books, estimate, fees)))
        slug = _selected_polymarket_slug(value, selected)
        _identity(value.get("market_slug") == slug and contract.get("source_url") == "https://gamma-api.polymarket.com/markets/slug/" + slug)
        instant = lambda stamp: datetime.fromisoformat(stamp.replace("Z", "+00:00"))
        _require(_time(contract.get("metadata_checked_at")) and instant(contract["metadata_checked_at"]) <= instant(value["captured_at"]))
        _require(_text(contract.get("question")) and bool(contract["question"].strip()) and isinstance(contract.get("condition_id"), str) and bool(re.fullmatch(r"0x[a-f0-9]{64}", contract["condition_id"])) and isinstance(contract.get("source_market_id"), str) and bool(re.fullmatch(r"[1-9]\d{0,99}", contract["source_market_id"])))
        _identity(market_id == "polymarket:condition-sha256:" + hashlib.sha256(("orrery-polymarket-canonical-identity.v1\0condition_id\0" + contract["condition_id"]).encode()).hexdigest())
        _require(isinstance(contract.get("response_sha256"), str) and bool(re.fullmatch(r"[a-f0-9]{64}", contract["response_sha256"])) and all(contract.get(key) is None or type(contract[key]) is bool for key in ("closed", "active")))
        if not include_cost:
            _require(fees.get("status") == "unknown" and fees.get("amount") is None and _text(fees.get("reason")))
        for selected_outcome, token_key in (("YES", "yes_token_id"), ("NO", "no_token_id")):
            token, book = contract.get(token_key), books.get(selected_outcome)
            _require(isinstance(token, str) and bool(re.fullmatch(r"[1-9]\d{0,77}", token)) and int(token) < 2 ** 256 and isinstance(book, dict))
            _identity(book.get("outcome") == selected_outcome and book.get("token_id") == token and book.get("source_url") == "https://clob.polymarket.com/book?token_id=" + token)
            _require(book.get("status") in ("fresh", "stale", "unavailable") and _time(book.get("captured_at")) and instant(contract["metadata_checked_at"]) <= instant(book["captured_at"]) <= instant(value["captured_at"]))
            _require(book.get("reason") is None or _text(book["reason"]))
            _require(book.get("min_order_size") is None or _depth_decimal(book["min_order_size"]) is not None)
            _require(book.get("tick_size") is None or _depth_decimal(book["tick_size"], maximum=1) is not None)
            for book_side in ("bids", "asks"):
                levels = book.get(book_side)
                _require(isinstance(levels, list) and len(levels) <= 2000)
                previous = None
                for row in levels:
                    _require(isinstance(row, dict))
                    price, size = _depth_decimal(row.get("price"), maximum=1), _depth_decimal(row.get("size"))
                    _require(price is not None and size is not None and (previous is None or (price > previous if book_side == "asks" else price < previous)))
                    previous = price
            if book["status"] == "unavailable":
                _require(book.get("observed_at") is None and book.get("response_sha256") is None and not book["bids"] and not book["asks"] and bool(book.get("reason")))
            else:
                _require(_time(book.get("observed_at")) and instant(book["observed_at"]) <= instant(book["captured_at"]) and isinstance(book.get("response_sha256"), str) and bool(re.fullmatch(r"[a-f0-9]{64}", book["response_sha256"])))
                _require(book["status"] != "fresh" or (instant(value["captured_at"]) - instant(book["observed_at"])).total_seconds() <= 120)
                _require(not book["bids"] or not book["asks"] or Decimal(book["bids"][0]["price"]) < Decimal(book["asks"][0]["price"]))
        _identity(contract["yes_token_id"] != contract["no_token_id"])
        expected_status = "collected" if all(book["status"] == "fresh" for book in books.values()) else "unavailable" if all(book["status"] == "unavailable" for book in books.values()) else "partial"
        _require(value["status"] == expected_status and estimate.get("status") in ("filled", "partial", "unavailable"))
        _identity(estimate.get("outcome") == outcome and estimate.get("side") == side and _depth_decimal(estimate.get("requested_shares"), maximum=1_000_000) == requested)
        _require(estimate.get("below_minimum_order_size") is None or type(estimate["below_minimum_order_size"]) is bool)
        _require(estimate.get("reason") is None or _text(estimate["reason"]))
        levels = estimate.get("consumed_levels")
        _require(isinstance(levels, list) and len(levels) <= 2000)
        if estimate["status"] == "unavailable":
            _require(books[outcome]["status"] != "fresh" and not levels and bool(estimate.get("reason")) and all(estimate.get(key) is None for key in ("filled_shares", "unfilled_shares", "vwap", "gross_notional", "worst_price")))
        else:
            filled, unfilled = (_depth_decimal(estimate.get(key), maximum=1_000_000, zero=True) for key in ("filled_shares", "unfilled_shares"))
            _require(books[outcome]["status"] == "fresh" and filled is not None and unfilled is not None and filled + unfilled == requested and (estimate["status"] == "filled") == (unfilled == 0))
            _require(_depth_decimal(estimate.get("gross_notional"), places=16, maximum=1_000_000, zero=True) is not None)
            _require(estimate.get("vwap") is None and estimate.get("worst_price") is None and not levels if filled == 0 else _depth_decimal(estimate.get("vwap"), places=12, maximum=1) is not None and _depth_decimal(estimate.get("worst_price"), maximum=1) is not None and bool(levels))
            _require(all(isinstance(row, dict) and _depth_decimal(row.get("price"), maximum=1) is not None and _depth_decimal(row.get("size"), maximum=1_000_000) is not None and _depth_decimal(row.get("notional"), places=16, maximum=1_000_000) is not None for row in levels))
        _validate_depth_estimate(value)
        if include_cost:
            _validate_purchase_cost(value, include_proceeds)
        return value

    def compare_contracts(self, market_ids: list[str] | tuple[str, ...], *, include_rules: bool = False) -> dict:
        _argument(isinstance(market_ids, (list, tuple)) and 2 <= len(market_ids) <= 3 and all(_market(item) for item in market_ids) and len(set(market_ids)) == len(market_ids), "invalid_market_selection", field="market_ids", message="Supply a list or tuple of 2 or 3 distinct canonical Polymarket or supported HIP-4 market IDs returned by search; public slugs and venue URLs are not accepted.")
        _argument(type(include_rules) is bool, "invalid_include_rules", field="include_rules", message="Use True for supported retained terms readings or False for the original field comparison.")
        selected = list(market_ids)
        query = [("market_id", item) for item in selected]
        if include_rules:
            query.extend((("include_rules", "true"), ("rules_version", "2")))
        _, _, value = self._get("/api/free/v1/contracts/compare", query)
        _require(value.get("schema_version") == "howsure.contract-comparison-response.v1" and value.get("scope") == "retained_serving_only")
        _identity(value.get("market_ids") == selected)
        serving, comparison = value.get("serving"), value.get("comparison")
        _require(isinstance(serving, dict) and serving.get("state") in ("live", "stale") and _time(serving.get("checked_at")))
        _require(isinstance(comparison, dict) and comparison.get("format") == "howsure.contract-comparison.v1" and comparison.get("equivalence") == "not_assessed" and comparison.get("capturedAt") == serving["checked_at"] and isinstance(comparison.get("fields"), list) and _texts(comparison.get("limitations")))
        contracts = comparison.get("contracts")
        _require(isinstance(contracts, list) and len(contracts) == len(selected))
        keys = []
        for row, market_id in zip(contracts, selected):
            _require(isinstance(row, dict))
            venue = "polymarket" if _POLY.fullmatch(market_id) else "hip4"
            _identity(row.get("id") == market_id and row.get("venue") == venue and row.get("key") == venue + ":" + market_id)
            keys.append(row["key"])
            observed = row.get("observation")
            _require(_text(row.get("question")) and type(row.get("archived")) is bool and isinstance(observed, dict) and observed.get("freshness") in ("fresh", "stale", "unknown"))
            probability, observed_at = observed.get("probability"), observed.get("observedAt")
            _require("probability" in observed and (probability is None or type(probability) in (int, float) and math.isfinite(probability) and 0 <= probability <= 1))
            _require(observed_at is None or _time(observed_at) and datetime.fromisoformat(observed_at.replace("Z", "+00:00")) <= datetime.fromisoformat(comparison["capturedAt"].replace("Z", "+00:00")))
            _require(probability is None or observed_at is not None)
        _identity(comparison.get("selectionKey") == "contracts:" + json.dumps(sorted(keys), separators=(",", ":")))
        _require(not include_rules or "ruleReading" in comparison)
        if "ruleReading" in comparison:
            _validate_comparison_rules(comparison)
        return value