astroapi-io-client 0.1.0__py3-none-any.whl

astroapi_client/_validation.py

@@ -0,0 +1,626 @@
+"""Bounded client-side shape checks; the server owns astronomical validation."""
+
+import json
+import math
+import re
+from datetime import date, datetime, timezone
+from typing import Any
+
+from .errors import ValidationError
+
+MIN_DATE = date(1900, 1, 1)
+MAX_DATE = date(2050, 12, 31)
+MAX_REQUEST_BYTES = 128 * 1024
+_BIRTH_FIELDS = {"date", "time", "lat", "lon", "timezone"}
+_FLAGS = {"zodiac", "ayanamsa"}
+_AYANAMSAS = {"lahiri", "raman", "krishnamurti", "fagan_bradley", "yukteshwar", "sassanian", "true_chitra", "true_revati", "true_pushya", "galactic_center_0_sagittarius", "galactic_alignment_mardyks"}
+_BODIES = {"sun", "moon", "mercury", "venus", "mars", "jupiter", "saturn", "rahu", "ketu"}
+_PLANETARY_EVENT_BODIES = {"sun", "moon", "mercury", "venus", "mars", "jupiter", "saturn", "uranus", "neptune", "pluto"}
+_PLANETARY_EVENT_TYPES = {"sign_ingress", "station", "aspect"}
+_PLANETARY_EVENT_ASPECTS = {"conjunction", "sextile", "square", "trine", "opposition"}
+_FIXED_STARS = {"aldebaran", "antares", "fomalhaut", "regulus", "sirius", "spica"}
+_EVENT_CALENDAR_TYPES = {"moon_phase", "sign_ingress", "station", "aspect", "aspect_window"}
+_SIGNS = {"Aries", "Taurus", "Gemini", "Cancer", "Leo", "Virgo", "Libra", "Scorpio", "Sagittarius", "Capricorn", "Aquarius", "Pisces"}
+_PHASE_SECTORS = {"new_moon", "waxing_crescent", "first_quarter", "waxing_gibbous", "full_moon", "waning_gibbous", "last_quarter", "waning_crescent"}
+_ASPECT_PROFILES = {"major", "standard", "extended"}
+_CONFIGURABLE_ASPECTS = {
+    "conjunction", "semisextile", "semisquare", "sextile", "quintile",
+    "square", "trine", "sesquiquadrate", "biquintile", "quincunx", "opposition",
+}
+
+
+def _invalid(message: str = "Request does not match the route's supported input fields.") -> None:
+    raise ValidationError(message)
+
+
+def _object(value: Any, allowed: set[str], required: set[str]) -> dict[str, Any]:
+    if not isinstance(value, dict) or not required <= value.keys() or value.keys() - allowed:
+        _invalid()
+    return value
+
+
+def _date(value: Any) -> None:
+    valid = False
+    if isinstance(value, str) and re.fullmatch(r"[0-9]{4}-[0-9]{2}-[0-9]{2}", value):
+        try:
+            valid = MIN_DATE <= date.fromisoformat(value) <= MAX_DATE
+        except ValueError:
+            pass
+    if not valid:
+        _invalid("Dates must use YYYY-MM-DD within 1900-01-01 through 2050-12-31.")
+
+
+def _time(value: Any) -> None:
+    if not isinstance(value, str) or not re.fullmatch(
+        r"(?:[01][0-9]|2[0-3]):[0-5][0-9](?::[0-5][0-9])?", value
+    ):
+        _invalid("Times must use valid HH:MM or HH:MM:SS values.")
+
+
+def _timezone(value: Any) -> None:
+    if not isinstance(value, str) or not 1 <= len(value) <= 256 or any(
+        ord(char) < 33 or ord(char) == 127 for char in value
+    ):
+        _invalid("timezone must be an IANA timezone name; use UTC for UTC instants.")
+
+
+def _birth(value: Any, flags: bool = False) -> None:
+    data = _object(value, _BIRTH_FIELDS | (_FLAGS if flags else set()), {"date", "time", "lat", "lon"})
+    _date(data["date"])
+    _time(data["time"])
+    for field, lower, upper in (("lat", -90, 90), ("lon", -180, 180)):
+        coordinate = data[field]
+        if type(coordinate) not in (int, float) or not lower <= coordinate <= upper:
+            _invalid("Coordinates must be finite JSON numbers within latitude/longitude bounds.")
+    if "timezone" in data:
+        _timezone(data["timezone"])
+
+
+def _enum(value: Any, choices: set[str], message: str) -> None:
+    if not isinstance(value, str) or value not in choices:
+        _invalid(message)
+
+
+def _instant(value: Any) -> datetime:
+    result = None
+    if isinstance(value, str) and len(value) <= 40 and re.fullmatch(
+        r"[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}"
+        r"(?:\.[0-9]{1,6})?(?:Z|[+-][0-9]{2}:[0-9]{2})", value
+    ):
+        try:
+            result = datetime.fromisoformat(value.replace("Z", "+00:00")).astimezone(timezone.utc)
+        except (ValueError, OverflowError):
+            pass
+    if result is None or not MIN_DATE <= result.date() <= MAX_DATE:
+        _invalid("Timeline boundaries require ISO timestamps with UTC offsets within 1900–2050.")
+    return result
+
+
+def _utc_second(value: Any) -> datetime:
+    result = None
+    if isinstance(value, str) and re.fullmatch(r"[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z", value):
+        try:
+            result = datetime.fromisoformat(value.replace("Z", "+00:00"))
+        except ValueError:
+            pass
+    lower = datetime(1900, 1, 1, tzinfo=timezone.utc)
+    upper = datetime(2051, 1, 1, tzinfo=timezone.utc)
+    if result is None or not lower <= result <= upper:
+        _invalid("Planetary event boundaries require whole-second UTC timestamps within 1900–2050.")
+    return result
+
+
+def _unique_enum_list(value: Any, choices: set[str], maximum: int, name: str) -> None:
+    if (not isinstance(value, list) or not 1 <= len(value) <= maximum
+            or any(not isinstance(item, str) or item not in choices for item in value)
+            or len(set(value)) != len(value)):
+        _invalid(f"{name} must be a bounded array of unique documented enum values.")
+
+
+def _aspect_configuration(data: dict[str, Any]) -> None:
+    if "aspect_profile" in data and "aspects" in data:
+        _invalid("aspect_profile and aspects are mutually exclusive.")
+    if "aspect_profile" in data:
+        _enum(data["aspect_profile"], _ASPECT_PROFILES,
+              "aspect_profile must be major, standard or extended.")
+    if "aspects" not in data:
+        return
+    if not isinstance(data["aspects"], list) or not 1 <= len(data["aspects"]) <= len(_CONFIGURABLE_ASPECTS):
+        _invalid("Aspects must contain one through eleven configurations.")
+    names = set()
+    for item in data["aspects"]:
+        item = _object(item, {"aspect", "max_orb_degrees"}, {"aspect", "max_orb_degrees"})
+        _enum(item["aspect"], _CONFIGURABLE_ASPECTS, "Invalid configurable aspect.")
+        if item["aspect"] in names:
+            _invalid("Configured aspects must be unique.")
+        names.add(item["aspect"])
+        orb = item["max_orb_degrees"]
+        if (type(orb) not in (int, float) or not math.isfinite(orb)
+                or not 0.1 <= orb <= 10
+                or abs(orb * 10 - round(orb * 10)) > 1e-9):
+            _invalid("Aspect orbs must be 0.1 through 10.0 in 0.1-degree increments.")
+
+
+def _onboarding_request(route: str, data: dict[str, Any]) -> None:
+    if route == "place-search":
+        _object(data, {"query", "country_codes", "limit"}, {"query"})
+        if type(data["query"]) is not str or not 2 <= len(data["query"]) <= 200:
+            _invalid("query must be a string containing 2 through 200 characters.")
+        if "country_codes" in data:
+            codes = data["country_codes"]
+            if (type(codes) is not list or not 1 <= len(codes) <= 5 or len(set(codes)) != len(codes)
+                    or any(type(code) is not str or re.fullmatch(r"[A-Z]{2}", code) is None for code in codes)):
+                _invalid("country_codes must contain 1 through 5 unique uppercase ISO alpha-2 codes.")
+        if "limit" in data and (type(data["limit"]) is not int or not 1 <= data["limit"] <= 10):
+            _invalid("limit must be an integer from 1 through 10.")
+    elif route == "timezone-resolve":
+        _object(data, {"place_id", "date", "time"}, {"place_id", "date", "time"})
+        if type(data["place_id"]) is not str or re.fullmatch(r"geonames:[1-9][0-9]{0,11}:2026-10-02", data["place_id"]) is None:
+            _invalid("place_id must be a current versioned AstroAPI GeoNames place ID.")
+        _date(data["date"])
+        _time(data["time"])
+    else:
+        _object(data, {"birth", "zodiac", "ayanamsa", "house_system", "formats"}, {"birth"})
+        _birth(data["birth"])
+        if "zodiac" in data:
+            _enum(data["zodiac"], {"tropical", "sidereal"}, "zodiac must be tropical or sidereal.")
+        if "ayanamsa" in data:
+            _enum(data["ayanamsa"], _AYANAMSAS, "ayanamsa is not supported.")
+        if "house_system" in data:
+            _enum(data["house_system"], {"equal", "whole_sign", "placidus"}, "house_system is not supported for natal context.")
+        if "formats" in data:
+            _unique_enum_list(data["formats"], {"json", "xml", "markdown"}, 3, "formats")
+
+
+def encode_request(route: str, payload: Any) -> bytes:
+    """Serialize once so the worker never retains a caller-owned mutable payload."""
+    encoded = None
+    try:
+        encoded = json.dumps(payload, ensure_ascii=True, allow_nan=False, separators=(",", ":")).encode("ascii")
+    except (TypeError, ValueError, OverflowError, RecursionError):
+        pass
+    if encoded is None:
+        _invalid("Request must contain only finite, JSON-serializable values.")
+    if len(encoded) > MAX_REQUEST_BYTES:
+        _invalid("Request exceeds the 128 KiB JSON body limit.")
+    # This copy also prevents a concurrent caller mutation from changing validation.
+    data = json.loads(encoded)
+    if route in {"place-search", "timezone-resolve", "natal-context"}:
+        _onboarding_request(route, data)
+        return encoded
+    if route == "numerology":
+        _object(data, {"birth_date", "name", "master_numbers", "y_vowel", "year"}, {"birth_date"})
+        _date(data["birth_date"])
+        if "name" in data and (type(data["name"]) is not str or re.fullmatch(r"[A-Za-z](?:[A-Za-z '\-]{0,94}[A-Za-z])?", data["name"]) is None):
+            _invalid("name requires 1-96 ASCII letters and internal separators; supply explicit transliteration.")
+        for flag in ("master_numbers", "y_vowel"):
+            if flag in data and type(data[flag]) is not bool: _invalid("Numerology flags must be booleans.")
+        if "y_vowel" in data and "name" not in data: _invalid("y_vowel requires name.")
+        if "year" in data and (type(data["year"]) is not int or not 1900 <= data["year"] <= 2050): _invalid("year must be an integer in 1900-2050.")
+    elif route == "birth-chart":
+        _birth(data, flags=True)
+    elif route in {"aspects", "houses", "transits", "horoscope"}:
+        extra = {"system"} if route == "houses" else set()
+        if route in {"transits", "horoscope"}:
+            extra |= {"transitDate", "transitTime", "timezone"}
+        required = {"birth", "transitDate"} if route == "transits" else {"birth"}
+        _object(data, {"birth"} | _FLAGS | extra, required)
+        _birth(data["birth"])
+        if "system" in data:
+            _enum(data["system"], {"equal", "whole_sign", "whole", "placidus", "porphyry", "meridian", "campanus", "regiomontanus", "alcabitius", "koch", "morinus", "topocentric", "sripati", "vehlow", "horizon", "krusinski", "sunshine", "sunshine_alt", "savard", "pullen_sd", "pullen_sr", "carter", "apc", "equal_mc", "natural", "gauquelin"}, "system must be equal, whole_sign, whole, placidus, porphyry, meridian, campanus, regiomontanus, alcabitius, koch, morinus, topocentric, sripati, vehlow, horizon, krusinski, sunshine, sunshine_alt, savard, pullen_sd, pullen_sr, carter, apc, equal_mc, natural, or gauquelin.")
+        if "transitDate" in data:
+            _date(data["transitDate"])
+        if "transitTime" in data:
+            _time(data["transitTime"])
+        if "timezone" in data:
+            _timezone(data["timezone"])
+    elif route == "natal-svg":
+        _object(data, {"birth", "house_system", "theme", "show_aspects", "additional_points", "aspect_profile", "aspects", "include_png"} | _FLAGS, {"birth"})
+        _birth(data["birth"])
+        if "house_system" in data:
+            _enum(data["house_system"], {"equal", "whole_sign", "placidus", "porphyry", "meridian", "campanus", "regiomontanus", "alcabitius", "koch", "morinus", "topocentric", "sripati", "vehlow", "horizon", "krusinski", "sunshine", "sunshine_alt", "savard", "pullen_sd", "pullen_sr", "carter", "apc", "equal_mc", "natural"}, "house_system must be equal, whole_sign, placidus, porphyry, meridian, campanus, regiomontanus, alcabitius, koch, morinus, topocentric, sripati, vehlow, horizon, krusinski, sunshine, sunshine_alt, savard, pullen_sd, pullen_sr, carter, apc, equal_mc, or natural.")
+        if "theme" in data:
+            _enum(data["theme"], {"light", "dark", "monochrome"}, "theme must be light, dark, or monochrome.")
+        if "show_aspects" in data and type(data["show_aspects"]) is not bool:
+            _invalid("show_aspects must be a JSON boolean.")
+        if "include_png" in data and type(data["include_png"]) is not bool:
+            _invalid("include_png must be a JSON boolean.")
+        if "additional_points" in data:
+            _unique_enum_list(data["additional_points"], {
+                "vertex", "antivertex", "equatorial_ascendant",
+                "equatorial_descendant", "lot_of_fortune", "lot_of_spirit",
+            }, 6, "additional_points")
+        _aspect_configuration(data)
+    elif route in {"vargas", "vimshottari", "varga-svg", "ashtakavarga"}:
+        allowed = {"birth", "ayanamsa"} | ({"division", "d150_method"} if route in {"vargas", "varga-svg"} else set())
+        if route == "varga-svg":
+            allowed |= {"layout", "theme", "include_png"}
+        if route == "vimshottari":
+            allowed |= {"depth"}
+        if route == "ashtakavarga":
+            allowed |= {"include_reductions"}
+        _object(data, allowed, {"birth"})
+        _birth(data["birth"])
+        if "division" in data and (type(data["division"]) is not int or data["division"] not in {1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 16, 20, 24, 27, 30, 40, 45, 60, 81, 108, 144, 150}):
+            _invalid("division must be one of 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 16, 20, 24, 27, 30, 40, 45, 60, 81, 108, 144, or 150.")
+        if "d150_method" in data:
+            _enum(data["d150_method"], {"pvr_jhora_own_sign_uniform_direct", "deva_keralam_chandra_kala_nadi_non_uniform", "deva_keralam_chandra_kala_nadi_uniform_direct", "parivritti_cyclic", "movable_aries_forward_fixed_taurus_reverse_dual_gemini_forward", "movable_aries_forward_fixed_scorpio_reverse_dual_sagittarius_forward", "movable_aries_forward_fixed_leo_reverse_dual_sagittarius_forward", "movable_source_sign_forward_fixed_source_sign_reverse_dual_source_sign_forward"}, "d150_method is invalid.")
+            if data.get("division") != 150:
+                _invalid("d150_method requires division 150.")
+        if "depth" in data and (type(data["depth"]) is not int or data["depth"] not in {2, 3, 4}):
+            _invalid("depth must be the JSON integer 2, 3, or 4.")
+        if "include_reductions" in data and type(data["include_reductions"]) is not bool:
+            _invalid("include_reductions must be a JSON boolean.")
+        if "layout" in data:
+            _enum(data["layout"], {"north_indian", "south_indian"}, "layout must be north_indian or south_indian.")
+        if "theme" in data:
+            _enum(data["theme"], {"light", "dark", "monochrome"}, "theme must be light, dark, or monochrome.")
+        if "include_png" in data and type(data["include_png"]) is not bool:
+            _invalid("include_png must be a JSON boolean.")
+    elif route == "moon-phases":
+        _object(data, {"mode", "at", "start", "end", "display_timezone", "include_ical"}, {"mode"})
+        _enum(data["mode"], {"instant", "calendar"}, "mode must be instant or calendar.")
+        fields = {"at"} if data["mode"] == "instant" else {"start", "end"}
+        optional = {"include_ical"} if data["mode"] == "calendar" else set()
+        _object(data, {"mode", "display_timezone"} | fields | optional, {"mode"} | fields)
+        if "include_ical" in data and type(data["include_ical"]) is not bool:
+            _invalid("include_ical must be boolean in calendar mode.")
+        for field in fields:
+            civil = _object(data[field], {"date", "time", "timezone"}, {"date", "time"})
+            _date(civil["date"])
+            _time(civil["time"])
+            if "timezone" in civil:
+                _timezone(civil["timezone"])
+                if len(civil["timezone"]) > 100:
+                    _invalid("Moon phase timezone names must be at most 100 characters.")
+        if "display_timezone" in data:
+            _timezone(data["display_timezone"])
+            if len(data["display_timezone"]) > 100:
+                _invalid("Moon phase timezone names must be at most 100 characters.")
+    elif route == "panchang":
+        _object(data, {"at", "ayanamsa"}, {"at"})
+        _birth(data["at"])
+        if abs(data["at"]["lat"]) > 88:
+            _invalid("Panchang beta latitude must be within inclusive [-88,88].")
+    elif route in {"lunar-nodes", "returns"}:
+        if route == "lunar-nodes":
+            _object(data, {"at"} | _FLAGS, {"at"})
+            civil = data["at"]
+        else:
+            _object(data, {"birth", "body", "after", "house_system", "location"} | _FLAGS, {"birth", "body", "after"})
+            _birth(data["birth"])
+            _enum(data["body"], {"sun", "moon"}, "body must be sun or moon.")
+            civil = data["after"]
+            if "house_system" in data:
+                _enum(data["house_system"], {"equal", "whole_sign"}, "Return house_system must be equal or whole_sign.")
+            if "location" in data:
+                location = _object(data["location"], {"lat", "lon"}, {"lat", "lon"})
+                for field, lower, upper in (("lat", -90, 90), ("lon", -180, 180)):
+                    if type(location[field]) not in (int, float) or not lower <= location[field] <= upper:
+                        _invalid("Coordinates must be finite JSON numbers within latitude/longitude bounds.")
+        _object(civil, {"date", "time", "timezone"}, {"date", "time"})
+        _date(civil["date"])
+        _time(civil["time"])
+        if "timezone" in civil:
+            _timezone(civil["timezone"])
+    elif route in {"composite", "davison"}:
+        _object(data, {"personA", "personB", "zodiac", "ayanamsa", "house_system"}, {"personA", "personB"})
+        _birth(data["personA"])
+        _birth(data["personB"])
+        if "house_system" in data:
+            _enum(data["house_system"], {"equal", "whole_sign"}, "Relationship house_system must be equal or whole_sign.")
+    elif route in {"secondary-progressions", "solar-arcs"}:
+        allowed = {"birth", "target", "zodiac", "ayanamsa", "house_system"}
+        if route == "solar-arcs":
+            allowed.add("method")
+        _object(data, allowed, {"birth", "target"})
+        _birth(data["birth"])
+        target = _object(data["target"], {"date", "time", "timezone"}, {"date", "time"})
+        _date(target["date"])
+        _time(target["time"])
+        if "timezone" in target:
+            _timezone(target["timezone"])
+        if "house_system" in data:
+            _enum(data["house_system"], {"equal", "whole_sign"}, "Natal context house_system must be equal or whole_sign.")
+        if route == "solar-arcs" and "method" in data:
+            _enum(data["method"], {"true_solar_arc", "mean_naibod"},
+                  "Solar arc method must be true_solar_arc or mean_naibod.")
+    elif route == "planetary-events":
+        _object(data, {"start_utc", "end_utc", "event_types", "bodies", "aspects"} | _FLAGS,
+                {"start_utc", "end_utc", "event_types", "bodies"})
+        start, end = _utc_second(data["start_utc"]), _utc_second(data["end_utc"])
+        if not 0 < (end - start).total_seconds() <= 31 * 86400:
+            _invalid("Planetary event range must be positive and no longer than 31 days.")
+        _unique_enum_list(data["event_types"], _PLANETARY_EVENT_TYPES, 3, "event_types")
+        _unique_enum_list(data["bodies"], _PLANETARY_EVENT_BODIES, 10, "bodies")
+        if "aspect" in data["event_types"]:
+            if len(data["bodies"]) < 2:
+                _invalid("Aspect searches require at least two bodies.")
+            if "aspects" in data:
+                _unique_enum_list(data["aspects"], _PLANETARY_EVENT_ASPECTS, 5, "aspects")
+        elif "aspects" in data:
+            _invalid("aspects is allowed only when event_types includes aspect.")
+    elif route == "house-ingresses":
+        _object(data, {"reference_birth", "start_utc", "end_utc", "bodies", "house_system"} | _FLAGS,
+                {"reference_birth", "start_utc", "end_utc", "bodies"})
+        _birth(data["reference_birth"])
+        if abs(data["reference_birth"]["lat"]) == 90:
+            _invalid("reference_birth latitude must exclude the geographic poles.")
+        start, end = _utc_second(data["start_utc"]), _utc_second(data["end_utc"])
+        if not 0 < (end - start).total_seconds() <= 31 * 86400:
+            _invalid("House-ingress range must be positive and no longer than 31 days.")
+        _unique_enum_list(data["bodies"], _PLANETARY_EVENT_BODIES, 10, "bodies")
+        if "house_system" in data:
+            _enum(data["house_system"], {"equal", "whole_sign"},
+                  "House-ingress house_system must be equal or whole_sign.")
+    elif route == "aspect-windows":
+        _object(data, {"start_utc", "end_utc", "bodies", "aspects", "orb_degrees", "include_ical"} | _FLAGS,
+                {"start_utc", "end_utc", "bodies"})
+        start, end = _utc_second(data["start_utc"]), _utc_second(data["end_utc"])
+        if not 0 < (end - start).total_seconds() <= 31 * 86400:
+            _invalid("Aspect-window range must be positive and no longer than 31 days.")
+        _unique_enum_list(data["bodies"], _PLANETARY_EVENT_BODIES, 10, "bodies")
+        if len(data["bodies"]) < 2:
+            _invalid("Aspect-window searches require at least two bodies.")
+        if "aspects" in data:
+            _unique_enum_list(data["aspects"], _PLANETARY_EVENT_ASPECTS, 5, "aspects")
+        if "orb_degrees" in data:
+            orb = data["orb_degrees"]
+            if type(orb) not in (int, float) or not math.isfinite(orb) or not 0.5 <= orb <= 10 or abs(orb * 10 - round(orb * 10)) > 1e-9:
+                _invalid("orb_degrees must be 0.5 through 10.0 in 0.1-degree increments.")
+        if "include_ical" in data and type(data["include_ical"]) is not bool:
+            _invalid("include_ical must be a boolean.")
+    elif route == "event-calendar":
+        _object(data, {"start_utc", "end_utc", "event_types", "bodies", "aspects", "orb_degrees", "zodiac", "ayanamsa", "display_timezone", "include_ical", "include_csv", "group_passes", "moon_phase_filter"}, {"start_utc", "end_utc", "event_types"})
+        start, end = _utc_second(data["start_utc"]), _utc_second(data["end_utc"])
+        if not 0 < (end - start).total_seconds() <= 31 * 86400:
+            _invalid("Event calendar range must be positive and no longer than 31 days.")
+        _unique_enum_list(data["event_types"], _EVENT_CALENDAR_TYPES, 5, "event_types")
+        if "moon_phase_filter" in data:
+            if "moon_phase" not in data["event_types"]:
+                _invalid("moon_phase_filter requires moon_phase events.")
+            _unique_enum_list(data["moon_phase_filter"], ("new_moon", "first_quarter", "full_moon", "last_quarter"), 4, "moon_phase_filter")
+        needs_bodies = any(item != "moon_phase" for item in data["event_types"])
+        if needs_bodies:
+            if "bodies" not in data:
+                _invalid("bodies is required for selected event types.")
+            _unique_enum_list(data["bodies"], _PLANETARY_EVENT_BODIES, 10, "bodies")
+        elif "bodies" in data:
+            _invalid("bodies is allowed only for planetary event types.")
+        needs_aspects = any(item in {"aspect", "aspect_window"} for item in data["event_types"])
+        if needs_aspects and len(data["bodies"]) < 2:
+            _invalid("Aspect calendar events require at least two bodies.")
+        if "aspects" in data:
+            if not needs_aspects:
+                _invalid("aspects is allowed only for aspect event types.")
+            _unique_enum_list(data["aspects"], _PLANETARY_EVENT_ASPECTS, 5, "aspects")
+        if "orb_degrees" in data:
+            orb = data["orb_degrees"]
+            if ("aspect_window" not in data["event_types"] or type(orb) not in (int, float)
+                    or not math.isfinite(orb) or not 0.5 <= orb <= 10
+                    or abs(orb * 10 - round(orb * 10)) > 1e-9):
+                _invalid("orb_degrees is valid only for aspect_window and must be 0.5 through 10.0 in 0.1-degree increments.")
+        if "display_timezone" in data:
+            _timezone(data["display_timezone"])
+            if len(data["display_timezone"]) > 100:
+                _invalid("display_timezone must be at most 100 characters.")
+        if "include_ical" in data and type(data["include_ical"]) is not bool:
+            _invalid("include_ical must be a boolean.")
+        if "include_csv" in data and type(data["include_csv"]) is not bool:
+            _invalid("include_csv must be a boolean.")
+        if "group_passes" in data:
+            if type(data["group_passes"]) is not bool:
+                _invalid("group_passes must be a boolean.")
+            if data["group_passes"] and not needs_aspects:
+                _invalid("group_passes requires aspect or aspect_window events.")
+    elif route in {"synastry-svg", "transit-svg", "natal-report"}:
+        if route == "synastry-svg":
+            _object(data, {"personA", "personB", "zodiac", "ayanamsa", "house_system", "theme", "show_aspects", "include_png"}, {"personA", "personB"})
+            _birth(data["personA"]); _birth(data["personB"])
+        elif route == "transit-svg":
+            _object(data, {"birth", "transitDate", "transitTime", "timezone", "zodiac", "ayanamsa", "house_system", "theme", "show_aspects", "include_png"}, {"birth", "transitDate"})
+            _birth(data["birth"]); _date(data["transitDate"])
+            if "transitTime" in data: _time(data["transitTime"])
+            if "timezone" in data: _timezone(data["timezone"])
+        else:
+            _object(data, {"birth", "zodiac", "ayanamsa", "house_system", "theme", "include_svg", "include_download", "download_format", "report_branding"}, {"birth"})
+            _birth(data["birth"])
+        if "house_system" in data:
+            _enum(data["house_system"], {"equal", "whole_sign", "placidus"}, "house_system must be equal, whole_sign or placidus.")
+        if "theme" in data: _enum(data["theme"], {"light", "dark", "monochrome"}, "theme must be light, dark, or monochrome.")
+        boolean_field = "include_svg" if route == "natal-report" else "show_aspects"
+        if boolean_field in data and type(data[boolean_field]) is not bool: _invalid(f"{boolean_field} must be a boolean.")
+        if route == "natal-report" and "include_download" in data and type(data["include_download"]) is not bool:
+            _invalid("include_download must be a boolean.")
+        if route == "natal-report" and "download_format" in data:
+            _enum(data["download_format"], {"html", "pdf", "docx", "xlsx", "ods", "epub", "odt", "rtf", "json", "csv", "xml", "ndjson", "tsv", "markdown", "text", "zip"}, "download_format must be html, pdf, docx, xlsx, ods, epub, odt, rtf, json, csv, xml, ndjson, tsv, markdown, text, or zip.")
+            if data.get("include_download") is not True:
+                _invalid("download_format requires include_download true.")
+        if route == "natal-report" and "report_branding" in data:
+            branding = _object(data["report_branding"], {"display_name", "accent"}, {"display_name"})
+            display_name = branding["display_name"]
+            if not isinstance(display_name, str) or re.fullmatch(
+                    r"[A-Za-z0-9](?:[A-Za-z0-9 &'().-]{0,62}[A-Za-z0-9])?", display_name) is None:
+                _invalid("report_branding.display_name must use 1-64 documented ASCII characters.")
+            if "accent" in branding:
+                _enum(branding["accent"], {"amber", "blue", "green"}, "report_branding.accent must be amber, blue, or green.")
+            if data.get("download_format", "html") != "html":
+                _invalid("report_branding is available only for the HTML report.")
+        if route != "natal-report" and "include_png" in data and type(data["include_png"]) is not bool:
+            _invalid("include_png must be a JSON boolean.")
+    elif route == "birth-time-sensitivity":
+        _object(data, {"start", "end", "birth_time", "lat", "lon", "zodiac", "ayanamsa", "house_system"}, {"lat", "lon"})
+        if "birth_time" in data:
+            if "start" in data or "end" in data:
+                _invalid("birth_time is mutually exclusive with start/end.")
+            workflow = data["birth_time"]
+            if isinstance(workflow, dict) and workflow.get("status") == "unknown":
+                workflow = _object(workflow, {"status", "date", "timezone"}, {"status", "date", "timezone"})
+                _date(workflow["date"]); _timezone(workflow["timezone"])
+            elif isinstance(workflow, dict) and workflow.get("status") == "approximate":
+                workflow = _object(workflow, {"status", "date", "time", "timezone", "uncertainty_minutes"}, {"status", "date", "time", "timezone", "uncertainty_minutes"})
+                _date(workflow["date"]); _time(workflow["time"]); _timezone(workflow["timezone"])
+                uncertainty = workflow["uncertainty_minutes"]
+                if type(uncertainty) is not int or not 5 <= uncertainty <= 180 or uncertainty % 5:
+                    _invalid("uncertainty_minutes must be an integer multiple of 5 from 5 through 180.")
+            else:
+                _invalid("birth_time status must be unknown or approximate.")
+        else:
+            if "start" not in data or "end" not in data:
+                _invalid("start and end are required when birth_time is omitted.")
+            moments = []
+            for name in ("start", "end"):
+                civil = _object(data[name], {"date", "time", "timezone"}, {"date", "time"})
+                _date(civil["date"]); _time(civil["time"])
+                if "timezone" in civil: _timezone(civil["timezone"])
+                moments.append(datetime.fromisoformat(f'{civil["date"]}T{civil["time"]}'))
+            if data["start"].get("timezone", "UTC") != data["end"].get("timezone", "UTC"):
+                _invalid("start and end must use the same timezone.")
+            if not 0 < (moments[1] - moments[0]).total_seconds() <= 6 * 3600:
+                _invalid("Birth-time sensitivity must span more than zero and no more than six civil hours.")
+        for field, lower, upper in (("lat", -90, 90), ("lon", -180, 180)):
+            if type(data[field]) not in (int, float) or not math.isfinite(data[field]) or not lower <= data[field] <= upper: _invalid("Coordinates are outside supported bounds.")
+        if "house_system" in data: _enum(data["house_system"], {"equal", "whole_sign", "placidus"}, "house_system must be equal, whole_sign or placidus.")
+    elif route == "relocation-chart":
+        _object(data, {"birth", "location", "zodiac", "ayanamsa", "house_system"}, {"birth", "location"})
+        _birth(data["birth"])
+        if abs(data["birth"]["lat"]) == 90: _invalid("Relocation birth latitude must exclude the poles.")
+        location = _object(data["location"], {"lat", "lon"}, {"lat", "lon"})
+        for field, lower, upper in (("lat", -90, 90), ("lon", -180, 180)):
+            if type(location[field]) not in (int, float) or not math.isfinite(location[field]) or not lower <= location[field] <= upper:
+                _invalid("Relocation coordinates are outside supported bounds.")
+        if abs(location["lat"]) == 90: _invalid("Relocation latitude must exclude the poles.")
+        if "house_system" in data: _enum(data["house_system"], {"equal", "whole_sign", "placidus"}, "house_system must be equal, whole_sign or placidus.")
+    elif route == "astrocartography":
+        _object(data, {"at", "bodies", "include_svg", "include_png", "theme", "basemap", "include_geojson", "include_geojson_seq", "include_ndjson", "include_topojson", "include_kml", "include_gpx", "include_csv", "include_wkt", "include_wkb", "include_gml"}, {"at", "bodies"})
+        at = _object(data["at"], {"date", "time", "timezone"}, {"date", "time"})
+        _date(at["date"]); _time(at["time"])
+        if "timezone" in at: _timezone(at["timezone"])
+        _unique_enum_list(data["bodies"], _PLANETARY_EVENT_BODIES, 10, "bodies")
+        if "basemap" in data:
+            _enum(data["basemap"], {"coordinate-grid-only", "natural-earth-110m"}, "Invalid basemap.")
+            if data.get("include_svg") is not True: _invalid("basemap requires include_svg true.")
+        if "include_svg" in data and type(data["include_svg"]) is not bool: _invalid("include_svg must be a boolean.")
+        if "include_geojson" in data and type(data["include_geojson"]) is not bool: _invalid("include_geojson must be a boolean.")
+        if "include_geojson_seq" in data and type(data["include_geojson_seq"]) is not bool: _invalid("include_geojson_seq must be a boolean.")
+        if "include_ndjson" in data and type(data["include_ndjson"]) is not bool: _invalid("include_ndjson must be a boolean.")
+        if "include_topojson" in data and type(data["include_topojson"]) is not bool: _invalid("include_topojson must be a boolean.")
+        if "include_kml" in data and type(data["include_kml"]) is not bool: _invalid("include_kml must be a boolean.")
+        if "include_gpx" in data and type(data["include_gpx"]) is not bool: _invalid("include_gpx must be a boolean.")
+        if "include_csv" in data and type(data["include_csv"]) is not bool: _invalid("include_csv must be a boolean.")
+        if "include_wkt" in data and type(data["include_wkt"]) is not bool: _invalid("include_wkt must be a boolean.")
+        if "include_wkb" in data and type(data["include_wkb"]) is not bool: _invalid("include_wkb must be a boolean.")
+        if "include_gml" in data and type(data["include_gml"]) is not bool: _invalid("include_gml must be a boolean.")
+        if "include_png" in data and type(data["include_png"]) is not bool: _invalid("include_png must be a boolean.")
+        if "theme" in data: _enum(data["theme"], {"light", "dark", "monochrome"}, "theme must be light, dark or monochrome.")
+        if data.get("include_svg") is not True and ("include_png" in data or "theme" in data):
+            _invalid("include_png and theme require include_svg true.")
+    elif route == "eclipse-geometry":
+        _object(data, {"start_utc", "end_utc", "eclipse_types", "observer"}, {"start_utc", "end_utc", "eclipse_types"})
+        start, end = _utc_second(data["start_utc"]), _utc_second(data["end_utc"])
+        if not 0 < (end - start).total_seconds() <= 366 * 86400:
+            _invalid("Eclipse geometry must span more than zero and at most 366 UTC days.")
+        _unique_enum_list(data["eclipse_types"], {"solar", "lunar"}, 2, "eclipse_types")
+        if "observer" in data:
+            observer = _object(data["observer"], {"lat", "lon"}, {"lat", "lon"})
+            for field, lower, upper in (("lat", -90, 90), ("lon", -180, 180)):
+                if type(observer[field]) not in (int, float) or not math.isfinite(observer[field]) or not lower <= observer[field] <= upper:
+                    _invalid("Observer coordinates must be finite numbers within range.")
+    elif route == "electional-search":
+        _object(data, {"start_utc", "end_utc", "location", "filters", "zodiac", "ayanamsa"}, {"start_utc", "end_utc", "location", "filters"})
+        start, end = _utc_second(data["start_utc"]), _utc_second(data["end_utc"])
+        if not 0 < (end - start).total_seconds() <= 7 * 86400:
+            _invalid("Electional search must span more than zero and at most seven UTC days.")
+        location = _object(data["location"], {"lat", "lon"}, {"lat", "lon"})
+        for field, lower, upper in (("lat", -90, 90), ("lon", -180, 180)):
+            if type(location[field]) not in (int, float) or not math.isfinite(location[field]) or not lower <= location[field] <= upper:
+                _invalid("Electional coordinates must be finite numbers within range.")
+        if abs(location["lat"]) == 90:
+            _invalid("Electional latitude must exclude the poles.")
+        filters = _object(data["filters"], {"moon_signs", "moon_phase_sectors", "mercury_motion", "ascendant_signs", "aspects"}, set())
+        if not filters:
+            _invalid("Electional filters must not be empty.")
+        if "moon_signs" in filters: _unique_enum_list(filters["moon_signs"], _SIGNS, 12, "moon_signs")
+        if "ascendant_signs" in filters: _unique_enum_list(filters["ascendant_signs"], _SIGNS, 12, "ascendant_signs")
+        if "moon_phase_sectors" in filters: _unique_enum_list(filters["moon_phase_sectors"], _PHASE_SECTORS, 8, "moon_phase_sectors")
+        if "mercury_motion" in filters: _enum(filters["mercury_motion"], {"direct", "retrograde"}, "mercury_motion must be direct or retrograde.")
+        if "aspects" in filters:
+            if not isinstance(filters["aspects"], list) or not 1 <= len(filters["aspects"]) <= 4:
+                _invalid("Electional aspects must contain one through four filters.")
+            identities = set()
+            for item in filters["aspects"]:
+                item = _object(item, {"body_a", "body_b", "aspect", "max_orb_degrees"}, {"body_a", "body_b", "aspect", "max_orb_degrees"})
+                _enum(item["body_a"], _PLANETARY_EVENT_BODIES, "Invalid aspect body.")
+                _enum(item["body_b"], _PLANETARY_EVENT_BODIES, "Invalid aspect body.")
+                _enum(item["aspect"], _PLANETARY_EVENT_ASPECTS, "Invalid major aspect.")
+                if item["body_a"] == item["body_b"]: _invalid("Aspect bodies must differ.")
+                orb = item["max_orb_degrees"]
+                if type(orb) not in (int, float) or not math.isfinite(orb) or not 0.5 <= orb <= 10 or abs(orb * 10 - round(orb * 10)) > 1e-9:
+                    _invalid("Electional aspect orb must be 0.5 through 10.0 in 0.1-degree increments.")
+                identity = (tuple(sorted((item["body_a"], item["body_b"]))), item["aspect"])
+                if identity in identities: _invalid("Electional aspect filters must be unique.")
+                identities.add(identity)
+    elif route == "natal-analysis":
+        _object(data, {"birth", "points", "aspects", "aspect_profile", "include_midpoints", "include_patterns", "include_graha_drishti", "include_shadbala_foundation", "additional_points", "zodiac", "ayanamsa"}, {"birth"})
+        _birth(data["birth"])
+        if "points" in data:
+            _unique_enum_list(data["points"], _PLANETARY_EVENT_BODIES, 10, "points")
+            if len(data["points"]) < 3: _invalid("Natal analysis requires at least three points.")
+        _aspect_configuration(data)
+        for field in ("include_midpoints", "include_patterns", "include_graha_drishti", "include_shadbala_foundation"):
+            if field in data and type(data[field]) is not bool: _invalid(f"{field} must be a boolean.")
+        if (data.get("include_graha_drishti") is True or data.get("include_shadbala_foundation") is True) and data.get("zodiac") != "sidereal":
+            _invalid("Vedic analysis options require explicit zodiac sidereal.")
+        if "additional_points" in data:
+            _unique_enum_list(data["additional_points"], {
+                "vertex", "antivertex", "equatorial_ascendant",
+                "equatorial_descendant", "lot_of_fortune", "lot_of_spirit",
+            }, 6, "additional_points")
+    elif route == "ashtakoota":
+        _object(data, {"groom", "bride", "ayanamsa"}, {"groom", "bride"})
+        _birth(data["groom"])
+        _birth(data["bride"])
+        if any(len(data[key].get("timezone", "UTC")) > 100 for key in ("groom", "bride")):
+            _invalid("Ashtakoota timezone must be at most 100 characters.")
+        if "ayanamsa" in data:
+            _enum(data["ayanamsa"], _AYANAMSAS, "ayanamsa must be lahiri, raman, krishnamurti, fagan_bradley, yukteshwar, sassanian or true_chitra, true_revati, true_pushya, galactic_center_0_sagittarius, or galactic_alignment_mardyks.")
+    elif route == "planetary-hours":
+        _object(data, {"date", "timezone", "lat", "lon"}, {"date", "timezone", "lat", "lon"})
+        _date(data["date"])
+        if data["date"] == MAX_DATE.isoformat(): _invalid("Planetary hours require a following civil date within the supported range.")
+        _timezone(data["timezone"])
+        for field, lower, upper in (("lat", -88, 88), ("lon", -180, 180)):
+            if type(data[field]) not in (int, float) or not math.isfinite(data[field]) or not lower <= data[field] <= upper:
+                _invalid("Planetary-hours coordinates are outside supported bounds.")
+    elif route == "fixed-stars":
+        _object(data, {"at", "stars", "zodiac", "ayanamsa"}, {"at", "stars"})
+        at = _object(data["at"], {"date", "time", "timezone"}, {"date", "time"})
+        _date(at["date"]); _time(at["time"])
+        if "timezone" in at: _timezone(at["timezone"])
+        _unique_enum_list(data["stars"], _FIXED_STARS, 6, "stars")
+    elif route == "synastry":
+        _object(data, {"personA", "personB"} | _FLAGS, {"personA", "personB"})
+        _birth(data["personA"])
+        _birth(data["personB"])
+    else:
+        fields = {"planet", "start_utc", "end_utc", "ayanamsa"}
+        _object(data, fields, fields)
+        _enum(data["planet"], _BODIES, "planet must be one of the nine supported timeline bodies.")
+        start, end = _instant(data["start_utc"]), _instant(data["end_utc"])
+        if not 0 < (end - start).total_seconds() <= 180 * 86400:
+            _invalid("Timeline range must be positive and no longer than 180 days.")
+    if route in {"natal-svg", "vargas", "vimshottari", "varga-svg", "ashtakavarga", "panchang", "composite", "davison", "secondary-progressions", "solar-arcs", "lunar-nodes", "returns"}:
+        inputs = ["personA", "personB"] if route in {"composite", "davison"} else ["at"] if route in {"panchang", "lunar-nodes"} else ["birth", "target"] if route in {"secondary-progressions", "solar-arcs"} else ["birth", "after"] if route == "returns" else ["birth"]
+        if any(len(data[key].get("timezone", "UTC")) > 100 for key in inputs):
+            _invalid("Beta route timezone must be at most 100 characters.")
+    if "zodiac" in data:
+        _enum(data["zodiac"], {"tropical", "sidereal"}, "zodiac must be tropical or sidereal.")
+    if "ayanamsa" in data:
+        _enum(data["ayanamsa"], _AYANAMSAS, "ayanamsa must be lahiri, raman, krishnamurti, fagan_bradley, yukteshwar, sassanian or true_chitra, true_revati, true_pushya, galactic_center_0_sagittarius, or galactic_alignment_mardyks.")
+    return encoded
+
+
+def positive_timeout(value: Any) -> float:
+    if type(value) not in (int, float) or not 0 < value <= 300 or not math.isfinite(value):
+        _invalid("Timeouts must be finite numbers greater than zero and at most 300 seconds.")
+    return float(value)