parse-sdk 0.1.0__py3-none-any.whl

parse_sdk/_runtime.py

@@ -0,0 +1,2142 @@
+"""Runtime base classes for generated per-API modules.
+
+Generated code (``parse_apis/<slug>/__init__.py``) imports from here.
+Anything user-facing lives in ``parse_sdk.__init__`` / ``parse_sdk.errors``
+so users get clean import paths; this file is the implementation surface.
+
+The design is "the SDK module's classes are real Python classes, the
+runtime base lives here." A generated class for a Reddit Post looks like:
+
+    @resource(name="Post", keyed_by="id")
+    class Post(Resource):
+        id: str
+        title: str
+        ...
+        def refresh(self) -> Post: ...
+
+with the methods produced by codegen calling into ``BaseAPI._request``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import random
+import time
+import types
+import urllib.parse
+from collections import deque
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from decimal import Decimal, InvalidOperation
+from enum import Enum
+from typing import (
+    Any,
+    Callable,
+    ClassVar,
+    Dict,
+    Generic,
+    Iterable,
+    Iterator,
+    List,
+    Optional,
+    TYPE_CHECKING,
+    Type,
+    TypeVar,
+    Union,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
+
+from parse_sdk._labels import split_top, strip_wrapper
+from parse_sdk._sanitize import CONTROL_BYTES as _EXCERPT_UNSAFE
+from parse_sdk.config import CANONICAL_HOST as _CANONICAL_HOST
+from parse_sdk.config import _host_is_trusted
+from parse_sdk.config import resolve as _resolve_config
+
+# Identifies SDK-originated calls on the wire so the backend can attribute usage
+# (e.g. PostHog) to the typed SDK + its version. Computed lazily + cached: the
+# version literal lives in ``parse_sdk.__init__``, which imports THIS module, so a
+# top-level import would cycle — by request time the package is fully loaded.
+_CLIENT_HEADER: Optional[str] = None
+
+
+def _client_header() -> str:
+    global _CLIENT_HEADER
+    if _CLIENT_HEADER is None:
+        try:
+            from parse_sdk import __version__ as _v
+        except Exception:  # pragma: no cover — never block a request on this
+            _v = "unknown"
+        _CLIENT_HEADER = f"parse-sdk-python/{_v}"
+    return _CLIENT_HEADER
+
+if TYPE_CHECKING:  # avoid runtime import cycle
+    # httpx is imported lazily (function-local in BaseAPI.__init__/_request):
+    # importing it costs ~32-35 ms, and `import parse_sdk` pulls this module,
+    # so every `parse` CLI invocation paid that before any transport ran (see
+    # plan 003). Kept here so the httpx annotations below resolve statically.
+    import httpx
+
+
+# ---------------------------------------------------------------------------
+# Request metadata (cost / quota / rate-limit control loop)
+#
+# The executor emits X-Credits-* and X-RateLimit-* headers on every response
+# so callers can self-pace. RequestMeta parses them once into typed Optional
+# fields; surfaced on success via ``client.last_meta`` and on errors via
+# ``err.meta``.
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class RequestMeta:
+    credits_charged: Optional[int] = None
+    credits_remaining: Optional[int] = None
+    credits_limit: Optional[int] = None
+    rate_limit_limit: Optional[int] = None
+    rate_limit_remaining: Optional[int] = None
+    rate_limit_reset: Optional[int] = None  # epoch seconds
+    burst_limit: Optional[int] = None
+    refill_per_min: Optional[int] = None
+    daily_limit: Optional[int] = None
+    daily_remaining: Optional[int] = None
+    daily_reset: Optional[int] = None  # duration seconds (NOT epoch — unlike rate_limit_reset)
+    retry_after: Optional[int] = None
+
+    @classmethod
+    def from_headers(cls, headers: Any) -> "RequestMeta":
+        def _i(name: str) -> Optional[int]:
+            v = headers.get(name)
+            if v is None and isinstance(headers, dict):
+                lower = name.lower()
+                for k, candidate in headers.items():
+                    if isinstance(k, str) and k.lower() == lower:
+                        v = candidate
+                        break
+            if v is None:
+                return None
+            try:
+                return int(v)
+            except (TypeError, ValueError):
+                return None
+
+        return cls(
+            credits_charged=_i("x-credits-charged"),
+            credits_remaining=_i("x-credits-remaining"),
+            credits_limit=_i("x-credits-limit"),
+            rate_limit_limit=_i("x-ratelimit-limit"),
+            rate_limit_remaining=_i("x-ratelimit-remaining"),
+            rate_limit_reset=_i("x-ratelimit-reset"),
+            burst_limit=_i("x-ratelimit-burst"),
+            refill_per_min=_i("x-ratelimit-refill-per-min"),
+            daily_limit=_i("x-ratelimit-daily-limit"),
+            daily_remaining=_i("x-ratelimit-daily-remaining"),
+            daily_reset=_i("x-ratelimit-daily-reset"),
+            retry_after=_i("retry-after"),
+        )
+
+
+# ---------------------------------------------------------------------------
+# Error hierarchy
+#
+# All errors inherit from ``ParseError``. Subclasses map to common HTTP
+# semantics; generated per-API modules subclass ``ParseError`` further for
+# domain-specific errors (e.g. ``SubredditPrivate``).
+# ---------------------------------------------------------------------------
+
+
+class ParseError(RuntimeError):
+    """Base class for all SDK-raised errors.
+
+    Attributes:
+        status_code: the PARSE GATEWAY's HTTP status (the response the SDK
+                     received), or 0 if the request never reached the server.
+                     When the gateway relays a target-site failure this is the
+                     gateway's wrapper status (e.g. 502), NOT the target's —
+                     see ``upstream_status_code`` for that.
+        body:        parsed JSON body when the server returned one, raw text otherwise.
+        code:        the wire error ``kind`` from the server's error envelope
+                     (e.g. ``input_not_found``) when one was sent, else None.
+                     Stable across APIs — branch on it for portable handling
+                     even where no domain error class matched.
+        snippet:     the target site's response-body excerpt relayed by the
+                     gateway's upstream-error envelope, else None.
+        upstream_status_code: the TARGET SITE's HTTP status relayed by the
+                     gateway's upstream-error envelope (e.g. 404 while
+                     ``status_code`` is the gateway's 502), else None.
+        url:         the target-site URL the gateway reported in its error
+                     envelope (the page the scraper was fetching when it
+                     failed), else None.
+    """
+
+    def __init__(self, status_code: int, message: str, body: Any = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+        # Control-loop metadata, populated by _request when a response exists.
+        # Declared here so `except ParseError as e: e.meta` is always safe —
+        # errors raised before a response (keyless auth, network) keep None.
+        self.meta: Optional[RequestMeta] = None
+        # Envelope-derived fields, populated by _build_error when the server's
+        # error body carries them. Declared here (same always-safe contract as
+        # ``meta``) so typed consumers can read them on ANY ParseError without
+        # hasattr probing.
+        self.code: Optional[str] = None
+        self.snippet: Optional[str] = None
+        self.upstream_status_code: Optional[int] = None
+        self.url: Optional[str] = None
+
+
+class AuthError(ParseError):
+    """401 — missing / invalid API key, or session expired."""
+
+
+class ForbiddenError(ParseError):
+    """403 — caller is authenticated but not allowed (rate-limited tier,
+    plan gating, etc.)."""
+
+
+class NotFoundError(ParseError):
+    """404 — resource doesn't exist or caller can't see it."""
+
+
+class BadRequestError(ParseError):
+    """400 — request shape was wrong; usually a missing required param
+    or a value the upstream rejected."""
+
+
+class RateLimitError(ParseError):
+    """429 — caller exceeded their token bucket or daily cap.
+
+    ``retry_after`` is the seconds-to-wait suggestion from the server, if any.
+    """
+
+    def __init__(self, status_code: int, message: str, body: Any = None,
+                 retry_after: Optional[int] = None) -> None:
+        super().__init__(status_code, message, body=body)
+        self.retry_after = retry_after
+
+
+class QuotaExceededError(ParseError):
+    """402 — the account ran out of credits / quota.
+
+    The executor returns 402 on paid-tier credit exhaustion (an account-wide
+    billing state, distinct from a malformed-param 400). The ``X-Credits-*``
+    headers are on ``err.meta``. Subclasses ``ParseError`` directly so a generic
+    ``except ParseError`` still catches it."""
+
+
+class UpstreamError(ParseError):
+    """502 / 503 / 504 — the target site was unreachable or returned a
+    non-success response that the scraper couldn't recover from.
+
+    ``status_code`` is the gateway's wrapper status (typically 502);
+    ``upstream_status_code`` is the target site's own status when the envelope
+    relayed one, and ``snippet`` is the target's response-body excerpt. A
+    sanitized, truncated snippet is appended to the message so ``str(e)`` and
+    uncaught tracebacks show the upstream payload; the full raw body stays on
+    ``.body`` / ``.snippet``."""
+
+
+class PaginationError(ParseError):
+    """The declared ``items_path`` is present in a successful response but does
+    NOT resolve to an array (``{jobs: {...}}`` / ``{jobs: 5}``) — the spec's
+    ``items_path`` is mis-derived (it points at a scalar/object, not the item
+    list), or the site's shape changed. Fail loud rather than yield silent
+    garbage.
+
+    Narrowed: an *absent* ``items_path`` on a successful response
+    is no longer a blanket error — a zero-result page that simply omits the key
+    (``{}`` / a top-level-list / an envelope-null body) returns ``[]``. The
+    raise is reserved for the unambiguous mis-derivation (key present, value not
+    a list) plus, in regenerated modules, the sample-proven case (the key was in
+    the captured sample but is absent now). See ``_extract_items`` and the
+    emitted discriminator."""
+
+
+class PaginationLimitError(ParseError):
+    """A ``Paginator`` could not advance further: stall, fetch budget, or the
+    upstream's result window ran out.
+
+    Raised when a paginated operation re-returns the same page of items (a
+    stalled pagination contract — e.g. the server doesn't surface a usable
+    next-cursor and the SDK's fabricated cursor is ignored), runs past
+    ``max_fetches``, or — mid-iteration, after at least one successful page —
+    the upstream refuses deeper pages with a 4xx (a result-window cap, e.g.
+    GitHub search stops serving past 1000 results). Carries no HTTP status —
+    it's a client-side guard, not a server response — so ``status_code`` is 0;
+    on the window-exhaustion path ``__cause__`` is the underlying
+    :class:`UpstreamError` (with ``upstream_status_code`` / ``snippet``).
+
+    Items already yielded before the raise are valid. ``pages_fetched`` /
+    ``items_yielded`` say how far iteration got. ``partial_items`` is
+    populated ONLY when the failure surfaces through :meth:`Paginator.list`;
+    on the direct ``__next__`` path — manual ``for`` iteration, ``list(
+    paginator)``, comprehensions — it stays ``None``. That is deliberate: a
+    ``for`` consumer already holds each item it was handed, and the streaming
+    paginator does not retain yielded items (a documented memory decision), so
+    there is nothing to backfill. Prefer ``.list()`` over ``list(paginator)``
+    when you need the materialized prefix to survive the raise.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        pages_fetched: Optional[int] = None,
+        items_yielded: Optional[int] = None,
+        partial_items: Optional[List[Any]] = None,
+    ) -> None:
+        super().__init__(0, message, body=None)
+        self.pages_fetched = pages_fetched
+        self.items_yielded = items_yielded
+        self.partial_items = partial_items
+
+
+# Console-hostile bytes stripped from message-embedded excerpts: C0 controls
+# minus \n\t (so \r IS stripped — a bare carriage return rewrites/hides
+# earlier terminal output even piped), DEL, and C1 (incl. the single-byte CSI
+# \x9b). The class is the single source in ``parse_sdk._sanitize`` (imported as
+# ``_EXCERPT_UNSAFE``), shared with ``_sync``/``cli`` so the two threat models
+# cannot drift. The raw bytes remain available on ``.body`` / ``.snippet``.
+_EXCERPT_LIMIT = 300
+
+
+def _sanitize_excerpt(text: str, limit: int = _EXCERPT_LIMIT) -> str:
+    """Control-strip + hard-truncate an untrusted string for message embedding."""
+    cleaned = _EXCERPT_UNSAFE.sub("", text)
+    if len(cleaned) > limit:
+        return cleaned[:limit] + "…"
+    return cleaned
+
+
+def _error_envelope(body: Any) -> Dict[str, Any]:
+    """The server's nested error envelope (``body['error']``) when present.
+
+    The executor raises ``HTTPException(status, detail={...})`` and its app-level
+    handler renames ``detail`` → ``error``, so envelope fields (``kind``,
+    ``snippet``, ``upstream_status_code``, ``retry_after``) live one level down.
+    Returns ``{}`` for any non-conforming body so callers can ``.get`` freely.
+    """
+    if isinstance(body, dict):
+        env = body.get("error")
+        if isinstance(env, dict):
+            return env
+    return {}
+
+
+def _build_error(
+    status_code: int,
+    body: Any,
+    fallback: str = "",
+    *,
+    error_classes: Optional[Dict[str, type]] = None,
+    headers: Optional["httpx.Headers"] = None,
+    params: Optional[Dict[str, Any]] = None,
+) -> ParseError:
+    """Pick the right exception subclass for an HTTP error response.
+
+    The executor emits a closed wire ``kind`` (``body['error']['kind']``, e.g.
+    ``input_not_found``). When the generated client passes its ``_ERROR_CLASSES``
+    registry (``{kind: GeneratedErrorClass}``) and the body's ``kind`` matches,
+    the DOMAIN class is raised BEFORE the coarse HTTP-status dispatch — so
+    ``except BookNotFound`` fires. The legacy ``body['error_code']`` spelling is
+    also honored. Falls through to the status table when there is no registry
+    or no match.
+
+    Every constructed error is finished uniformly: ``code`` (the wire kind),
+    ``snippet``, ``upstream_status_code`` and ``url`` are lifted from the
+    envelope, and —
+    for a matched DOMAIN class — declared ``carries`` are hydrated from the
+    caller's REQUEST PARAMS via the class's generated ``_CARRY_PARAMS`` map
+    (``{attr_ident: wire_param_name}``). Carries hydrate only when the request
+    actually sent the named param and the attribute is still None, so a future
+    server-provided carry value is never clobbered. The response body is never
+    read for carry values.
+
+    For 429, ``retry_after`` is read from the ``Retry-After`` *header* first
+    (the reliable, CORS-exposed signal the executor's rate_limit_service sets),
+    then from the body. The executor nests the body value at
+    ``body['error']['retry_after']`` (its custom handler renames detail→error),
+    so the body fallback walks BOTH the flat and nested paths.
+    """
+    kind = _wire_error_kind(body)
+    msg = _structured_error_message(body)
+    if msg is None:
+        # No structured message anywhere in the body (HTML gateway page, or a
+        # kind-only error object). The agent still needs something actionable:
+        # enrich the caller's context line with the structured facts in hand —
+        # the HTTP status (always) and the wire kind (when present). Never a
+        # body dump (pinned design: structured fields only).
+        bits = [f"HTTP {status_code}"]
+        if kind is not None:
+            bits.append(f"kind={kind}")
+        msg = f"{fallback or 'request failed'} ({', '.join(bits)})"
+    envelope = _error_envelope(body)
+    snippet = envelope.get("snippet")
+    snippet = snippet if isinstance(snippet, str) and snippet else None
+    upstream_sc = envelope.get("upstream_status_code")
+    upstream_sc = upstream_sc if isinstance(upstream_sc, int) else None
+    url = envelope.get("url")
+    url = url if isinstance(url, str) and url else None
+    # On a 429, the server's Retry-After hint must survive even when a generated
+    # DOMAIN error class matches the body's kind — the domain branch returns
+    # before the 429 status branch below. Compute it up front and attach it so
+    # the retry loop's getattr(err, "retry_after", None) honors it either way.
+    retry_after = _parse_retry_after(headers, body) if status_code == 429 else None
+
+    def _finish(err: ParseError) -> ParseError:
+        err.code = kind
+        err.snippet = snippet
+        err.upstream_status_code = upstream_sc
+        err.url = url
+        return err
+
+    if error_classes and kind is not None:
+        cls = error_classes.get(kind)
+        if cls is not None:
+            obj = cls(status_code, msg, body=body)
+            if retry_after is not None:
+                obj.retry_after = retry_after
+            # Hydrate declared carries from the request params (never the
+            # response body — the envelope is executor metadata, not domain
+            # values). _CARRY_PARAMS maps attr ident → wire param name and is
+            # emitted only for carries that exist in the API's input-param
+            # union, so absent mappings stay None by design.
+            carry_map = getattr(cls, "_CARRY_PARAMS", None)
+            if isinstance(carry_map, dict) and params:
+                for attr, src in carry_map.items():
+                    if src in params and getattr(obj, attr, None) is None:
+                        setattr(obj, attr, params[src])
+            return _finish(obj)
+    if status_code == 401:
+        return _finish(AuthError(status_code, msg, body=body))
+    if status_code == 403:
+        return _finish(ForbiddenError(status_code, msg, body=body))
+    if status_code == 404:
+        return _finish(NotFoundError(status_code, msg, body=body))
+    if status_code == 429:
+        return _finish(RateLimitError(status_code, msg, body=body, retry_after=retry_after))
+    if status_code == 402:
+        # Credit / quota exhaustion (executor's paid-tier billing state). Above
+        # the 4xx catch-all so it isn't mis-typed as a malformed-param 400;
+        # below the registry block so a future kind-carrying 402 still routes to
+        # a domain class.
+        return _finish(QuotaExceededError(status_code, msg, body=body))
+    if 400 <= status_code < 500:
+        return _finish(BadRequestError(status_code, msg, body=body))
+    if snippet:
+        # Surface the upstream payload where the user actually looks — str(e)
+        # and uncaught tracebacks. The full raw value stays on .snippet/.body.
+        msg = f"{msg} — upstream body (first {_EXCERPT_LIMIT} non-control chars): {_sanitize_excerpt(snippet)}"
+    return _finish(UpstreamError(status_code, msg, body=body))
+
+
+def _parse_retry_after(
+    headers: Optional["httpx.Headers"], body: Any
+) -> Optional[int]:
+    """Seconds-to-wait from the ``Retry-After`` header (primary) or the body.
+
+    Header first (reliable / CORS-exposed). Body fallback covers the flat
+    ``body['retry_after']``, the executor-nested ``body['error']['retry_after']``,
+    and the legacy ``body['detail']['retry_after']``. Returns None when no
+    usable signal exists. Never raises."""
+    if headers is not None:
+        raw = headers.get("Retry-After")
+        if raw is not None:
+            try:
+                return int(raw)
+            except (TypeError, ValueError):
+                pass  # HTTP-date form not handled — fall through to body
+    if isinstance(body, dict):
+        nested = body.get("error")
+        nested = nested if isinstance(nested, dict) else {}
+        detail = body.get("detail")
+        detail = detail if isinstance(detail, dict) else {}
+        ra = body.get("retry_after")
+        if ra is None:
+            ra = nested.get("retry_after")
+        if ra is None:
+            ra = detail.get("retry_after")
+        try:
+            return int(ra) if ra is not None else None
+        except (TypeError, ValueError):
+            return None
+    return None
+
+
+def _wire_error_kind(body: Any) -> Optional[str]:
+    """The executor's closed wire ``kind`` for an error body, or ``None``.
+
+    Walks the same shapes ``_build_error``'s registry dispatch always has:
+    nested ``body['error']['kind']`` / ``['code']``, then the legacy flat
+    ``body['error_code']`` / ``body['kind']`` spellings."""
+    if not isinstance(body, dict):
+        return None
+    kind: Any = None
+    err = body.get("error")
+    if isinstance(err, dict):
+        kind = err.get("kind") or err.get("code")
+    if kind is None:
+        kind = body.get("error_code") or body.get("kind")
+    return kind if isinstance(kind, str) else None
+
+
+def _structured_error_message(body: Any) -> Optional[str]:
+    """The human message from the body's structured string fields, or ``None``
+    when the body carries no usable message (non-dict, or kind-only)."""
+    if isinstance(body, dict):
+        for key in ("detail", "error", "message"):
+            v = body.get(key)
+            if isinstance(v, str):
+                return v
+            if isinstance(v, dict):
+                m = v.get("message") or v.get("error")
+                if isinstance(m, str):
+                    return m
+    return None
+
+
+def _format_error_message(body: Any, fallback: str = "") -> str:
+    return _structured_error_message(body) or fallback or "unknown error"
+
+
+# ---------------------------------------------------------------------------
+# Value coercion — driven by the codegen's per-field type label
+# ---------------------------------------------------------------------------
+
+
+# Non-downcast runtime backstop. When a NON-KEY field declared ``str`` is handed a non-str
+# wire value, downcasting it (``str(False) == 'False'``) changes the observed
+# data shape and can hide a stale/misdeclared schema. Keep such values RAW so an
+# already-shipped or drift-stale package stays non-corrupting without a regen.
+# KEY fields are EXCLUDED (they must keep downcasting so ``'42'`` and ``42``
+# stay ==/hash-equal for dedup). Unconditional — no env opt-out: an in-band
+# escape hatch is an agent-flippable vector that would reintroduce the exact
+# downcast corruption this backstop exists to prevent.
+# This covers ONLY the per-field annotation walk (``_coerce_by_annotation``); the
+# bare-scalar method-RETURN router (``_PRIMITIVE_COERCERS['str']`` via
+# ``coerce()``) is not a field-corruption vector and is left unchanged.
+
+# Monotonic clock seam — module-level so tests can monkeypatch wall-clock (the
+# retry budget counts real elapsed time, requests included).
+_monotonic = time.monotonic
+
+
+def _coerce_bool(value: Any) -> Any:
+    if value is None or isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        folded = value.strip().lower()
+        if folded in {"true", "t", "1", "yes", "y", "on"}:
+            return True
+        if folded in {"false", "f", "0", "no", "n", "off"}:
+            return False
+        return value
+    if isinstance(value, (int, float)) and value in (0, 1):
+        return bool(value)
+    return value
+
+
+_PRIMITIVE_COERCERS: Dict[str, Callable[[Any], Any]] = {
+    "str": lambda v: v if isinstance(v, str) else (str(v) if v is not None else None),
+    "int": lambda v: int(v) if v is not None else None,
+    "float": lambda v: float(v) if v is not None else None,
+    "bool": _coerce_bool,
+    "url": str,
+    "email": str,
+}
+
+
+def _coerce_datetime(value: Any) -> Any:
+    if value is None or isinstance(value, datetime):
+        return value
+    # ``bool`` subclasses ``int`` — guard it BEFORE the epoch branch so a wire
+    # ``True`` doesn't become ``1970-01-01T00:00:01`` (epoch 1). A bool is never
+    # a timestamp; pass it through raw.
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        try:
+            return datetime.fromtimestamp(value, tz=timezone.utc)
+        except (OSError, OverflowError, ValueError):
+            return value
+    if isinstance(value, str):
+        try:
+            return datetime.fromisoformat(value.replace("Z", "+00:00"))
+        except ValueError:
+            return value
+    return value
+
+
+def _coerce_decimal(value: Any) -> Any:
+    if value is None or isinstance(value, Decimal):
+        return value
+    try:
+        return Decimal(str(value))
+    except (InvalidOperation, TypeError):
+        return value
+
+
+# Sentinel: the dict carried no single list to unwrap (zero list fields, or
+# two-or-more NON-EMPTY list fields — genuinely ambiguous). Distinct from a
+# determinable empty result (``[]``). Each call-site decides the disposition.
+_NO_SINGLE_LIST = object()
+
+
+def _unwrap_single_list(value: Dict[str, Any]) -> Any:
+    """Pick the single list out of an envelope dict, or ``_NO_SINGLE_LIST``.
+
+    API responses often wrap a list in an envelope, e.g.
+    ``{"count": 3, "stories": [...]}``. When exactly ONE list-valued field is
+    non-empty we return it; an incidental EMPTY list (``{"errors": [],
+    "stories": [...]}``) is **ignored when counting** so a stray ``errors: []``
+    can't flip the count to 2 and defeat the unwrap. When every list field is
+    empty (``{"errors": [], "stories": []}``) we return ``[]`` — a determinable
+    empty result, not an ambiguity. Zero list fields, or two-or-more non-empty
+    list fields, return ``_NO_SINGLE_LIST`` — the caller decides whether to fail
+    loud (a method-return contract boundary) or degrade to raw (a per-field
+    walk that must never crash a successful scrape).
+
+    ``value`` is assumed to be a dict (callers guard ``isinstance``). Never
+    raises.
+    """
+    list_fields = [k for k, v in value.items() if isinstance(v, list)]
+    if not list_fields:
+        return _NO_SINGLE_LIST
+    non_empty = [k for k in list_fields if value[k]]
+    if len(non_empty) == 1:
+        return value[non_empty[0]]
+    if not non_empty:
+        # All list fields are empty → an empty result set (determinable).
+        return []
+    # Two-or-more non-empty lists → genuinely ambiguous.
+    return _NO_SINGLE_LIST
+
+
+def _construct_from_scalar(
+    cls: "Type[Resource]", value: Any, *, api: Optional["BaseAPI"], parent: Any
+) -> Any:
+    """Hydrate a constructible resource from a bare scalar matching its
+    ``keyed_by`` field (``post.subreddit = "smallbusiness"`` →
+    ``Subreddit(name="smallbusiness")``), or return ``value`` unchanged.
+
+    The scalar is COERCED to the key field's resolved annotation first (via the
+    total/lenient ``_coerce_by_annotation``), so the scalar-path instance and a
+    dict-path instance of the same entity agree on the key's TYPE — otherwise a
+    wire int key (``42``) on the scalar path vs an int-coerced ``42`` on the
+    dict path could diverge and break ``__eq__``/``__hash__`` (which key on the
+    field value). Only ``str``/``int`` scalars hydrate; anything else passes
+    through. Never raises (coercion is lenient).
+    """
+    key = getattr(cls, "_KEY_FIELD", None)
+    if not (getattr(cls, "_CONSTRUCTIBLE", False) and key and isinstance(value, (str, int))):
+        return value
+    key_ann = cls._field_hints().get(key)
+    coerced_key = (
+        _coerce_by_annotation(value, key_ann, api=api, parent=parent, is_key=True)
+        if key_ann is not None
+        else value
+    )
+    return cls(_api=api, _parent=parent, **{key: coerced_key})
+
+
+def _is_husk(inst: Any) -> bool:
+    """Husk predicate, observed by POST-``_from_payload`` instance
+    inspection — never by re-running the wrapped-record unwrap.
+
+    A husk is a constructed resource where *no declared wire key resolved* (the
+    ``_resolved_count`` signal ``_from_payload`` set is 0) — this single count
+    also subsumes "all declared keys null", since a key whose wire value is null
+    is not counted as resolved.
+
+    **Exempt** when ``_extra`` carries any non-null unmapped key: a record whose
+    data landed entirely in ``_extra`` is a mis-DERIVED spec (the fields were
+    typed off the wrong shape), NOT a hollow husk — failing loud there would
+    discard data the caller can still reach via ``obj._extra``. Total/lenient:
+    a missing signal (a non-``_from_payload`` instance) reads as NOT a husk, so
+    this can never manufacture a false verdict.
+    """
+    if getattr(inst, "_resolved_count", None) != 0:
+        return False
+    extra = getattr(inst, "_extra", None)
+    if isinstance(extra, dict) and any(v is not None for v in extra.values()):
+        return False  # data lives in _extra → mis-derived spec, not a husk
+    return True
+
+
+def coerce(value: Any, type_label: str, *, resource_classes: Optional[Dict[str, Type[Resource]]] = None,
+           api: Optional[BaseAPI] = None, parent: Any = None,
+           boundary: bool = False, mode: str = "element") -> Any:
+    """Coerce a raw response value to its declared type.
+
+    Type labels:
+      * ``str``, ``int``, ``float``, ``bool``         — primitive coercion
+      * ``datetime``                                   — int/float epoch OR ISO str → datetime
+      * ``Decimal``                                    — str/int/float → Decimal
+      * ``url``, ``email``                             — kept as str (semantic only)
+      * ``List[X]``                                    — recurse over each element
+      * ``Optional[X]``                                — None passes through; else recurse
+      * ``Dict[K, V]``                                 — recurse over values (keys stay str)
+      * ``Any``                                        — pass through unchanged
+      * ``<ResourceName>``                             — look up in ``resource_classes`` and
+                                                        construct an instance via ``_from_payload``
+
+    ``resource_classes`` / ``api`` / ``parent`` are forwarded so resource
+    instances can wire back to the owning client.
+
+    ``boundary`` / ``mode`` (return-fail-loud) gate the strict
+    return-boundary verdicts. **Both default to the LENIENT setting**
+    (``boundary=False``, ``mode='element'``) so an old 3-arg
+    ``_coerce(value, type_label, ctx)`` call from an already-generated module
+    hits the lenient default and behaves exactly as before — this is the
+    cross-compat protection for the entire generated fleet. The strict
+    husk / scalar verdicts fire ONLY when a *regenerated* module's
+    single-resource return passes ``boundary=True, mode='return'`` and the
+    declared type resolves to a Resource. Every ``Optional`` / ``List`` /
+    ``Dict`` recurse flips ``boundary=False`` (a verdict applies to the top
+    return only, never to a nested element — per-element disposition is the
+    lenient degrade-to-raw).
+    """
+    if value is None:
+        return None
+
+    t = type_label.strip()
+    # Optional[X] — single-layer unwrap via the shared label grammar (_labels).
+    _opt_inner = strip_wrapper(t, "Optional[")
+    if _opt_inner is not None:
+        return coerce(value, _opt_inner, resource_classes=resource_classes, api=api, parent=parent,
+                      boundary=False, mode=mode)
+    # List[X]
+    _list_inner = strip_wrapper(t, "List[")
+    if _list_inner is not None:
+        inner = _list_inner
+        # API responses often wrap the list in an envelope, e.g.
+        # ``{"count": 3, "stories": [...]}``. When we expect List[X] and got a
+        # dict, unwrap the single (non-empty) list. This is the method-RETURN
+        # contract boundary — the caller did ``return _coerce(_resp, 'List[X]',
+        # self)`` and will iterate the result, so a dict we can't unwrap to a
+        # list would silently iterate dict KEYS. FAIL LOUD instead (a clear
+        # error beats silent garbage). The per-FIELD router stays lenient.
+        if isinstance(value, dict):
+            unwrapped = _unwrap_single_list(value)
+            if unwrapped is _NO_SINGLE_LIST:
+                raise ParseError(
+                    0,
+                    f"expected List[{inner}] but the response was a dict with no "
+                    f"single list to unwrap (keys: {sorted(value)}); the "
+                    f"pagination/envelope contract is likely mis-derived",
+                    body=value,
+                )
+            value = unwrapped
+        if not isinstance(value, list):
+            return value
+        # Coverage symmetry: a non-paginated List[Resource] recurses at
+        # boundary=False — every element gets the SAME lenient degrade-to-raw
+        # disposition as a paginated row, never the strict return verdict.
+        return [coerce(v, inner, resource_classes=resource_classes, api=api, parent=parent,
+                       boundary=False, mode=mode) for v in value]
+    # Dict[K, V] — only coerce values
+    _dict_inner = strip_wrapper(t, "Dict[")
+    if _dict_inner is not None:
+        inner = _dict_inner
+        # First depth-0 comma split (handles Dict[str, List[X]]) — shared
+        # splitter; everything past the first comma is the value label.
+        parts = split_top(inner)
+        v_label = ", ".join(parts[1:]) if len(parts) > 1 else "Any"
+        if not isinstance(value, dict):
+            return value
+        return {k: coerce(v, v_label, resource_classes=resource_classes, api=api, parent=parent,
+                          boundary=False, mode=mode)
+                for k, v in value.items()}
+    # Primitives
+    if t in _PRIMITIVE_COERCERS:
+        try:
+            return _PRIMITIVE_COERCERS[t](value)
+        except (TypeError, ValueError, OverflowError):
+            # OverflowError: ``int(float('inf'))`` (stdlib json.loads admits
+            # Infinity/-Infinity/NaN, so a target can return ``{"n": Infinity}``
+            # on a declared-int field). Degrade to raw — never raise on a
+            # successful scrape.
+            return value
+    if t == "datetime":
+        return _coerce_datetime(value)
+    if t == "Decimal":
+        return _coerce_decimal(value)
+    if t in ("Any", "any"):
+        return value
+    # Resource type
+    if resource_classes and t in resource_classes:
+        cls = resource_classes[t]
+        # Strict return boundary — fires ONLY for a regenerated module's
+        # single-resource return (boundary=True + mode='return'). Anywhere else
+        # (lenient default, per-element rows at mode='element', any nested
+        # recurse at boundary=False) keeps the historical silent disposition.
+        strict = boundary and mode == "return"
+        if isinstance(value, dict):
+            inst = cls._from_payload(value, api=api, parent=parent)
+            if strict and _is_husk(inst):
+                # Husk: no declared wire key resolved OR all declared
+                # keys null — but EXEMPT when ``_extra`` carries non-null
+                # unmapped keys (a mis-DERIVED spec whose data lives in _extra,
+                # not a hollow husk — failing loud there would discard
+                # retrievable data). Husk-ness is observed by POST-_from_payload
+                # instance inspection (the resolved-key signal _from_payload
+                # set), never by re-running the unwrap. The verdict lives HERE
+                # in coerce(), never in _from_payload (shared with the lenient
+                # per-field router → a verdict there would crash the fleet).
+                raise ParseError(
+                    0,
+                    f"expected {t} but the response resolved no declared field "
+                    f"(an all-null / zero-key 'husk'); the return-type contract "
+                    f"is likely mis-derived",
+                    body=value,
+                )
+            return inst
+        # Constructible resources hydrate from a bare scalar matching the
+        # keyed_by field — the key is coerced to its annotation so scalar- and
+        # dict-path instances agree on key type (see _construct_from_scalar).
+        hydrated = _construct_from_scalar(cls, value, api=api, parent=parent)
+        if strict and not isinstance(hydrated, cls):
+            # Scalar husk: a bare scalar typed as a non-constructible Resource (no
+            # _KEY_FIELD to hydrate from) returned the raw scalar — fail loud.
+            # A constructible resource hydrated above (``isinstance`` holds), so
+            # only the genuinely non-constructible scalar reaches this raise.
+            raise ParseError(
+                0,
+                f"expected {t} but the response was a bare {type(value).__name__} "
+                f"with no key field to construct from; the return-type contract "
+                f"is likely mis-derived",
+                body=value,
+            )
+        return hydrated
+    # Unknown — pass through. Better to let user see the raw dict than crash.
+    return value
+
+
+# ---------------------------------------------------------------------------
+# Per-field coercion — single-source, driven by the resolved field ANNOTATION
+#
+# This is the per-field coercer (distinct from the ``coerce()`` string-label
+# *return* router above, which generated methods still call). Generated
+# resource classes declare each field's type as a PEP-526 annotation and carry
+# NO parallel ``_FIELDS`` label dict; ``_from_payload`` resolves those
+# annotations to real typing/class OBJECTS (cached per class) and dispatches on
+# them here — never round-tripping a resolved object back through the
+# string-label router (that would no-op and re-create the static/runtime
+# divergence). Total / lenient: an unknown form or un-coercible value passes
+# through raw; it never raises on a successful scrape.
+#
+# WHY TWO DISPATCHERS (do not naively merge): the leaf coercers
+# (_coerce_bool/_coerce_datetime/_coerce_decimal) are ALREADY single-sourced and
+# shared by both. What differs is irreducible and opposite: ``coerce()`` is the
+# RETURN router — it always downcasts ``str`` and FAILS LOUD at the strict boundary
+# (husk/scalar verdicts); this per-field router is LENIENT (degrade-to-raw),
+# honours the str non-downcast rule (``is_key``), and owns the Enum case-fold dispatch.
+# Folding them into one driver would re-encode those divergent dispositions as
+# flags (fail-loud-vs-lenient × is_key × boundary/mode) — more branching, not
+# less — in a path NO emitted-bytes gate can verify. The asymmetries are pinned
+# by tests/test_coercion_asymmetries.py. Keep them two.
+# ---------------------------------------------------------------------------
+
+
+# Both union spellings: ``typing.Union[...]`` (incl. ``Optional[X]``) and the
+# PEP-604 ``A | B`` form, whose origin is ``types.UnionType`` (3.10+). The
+# codegen emits ``Sort | str`` for enum/choice fields, so this is load-bearing.
+_UNION_ORIGINS = (Union, types.UnionType)
+
+
+def _coerce_by_annotation(
+    value: Any,
+    ann: Any,
+    *,
+    api: Optional[BaseAPI] = None,
+    parent: Any = None,
+    is_key: bool = False,
+) -> Any:
+    """Coerce ``value`` to the resolved annotation OBJECT ``ann``.
+
+    Dispatches on ``get_origin`` / ``get_args`` (List/Dict/Optional/Union),
+    ``isinstance``-against-``Enum``, and the ``datetime``/``Decimal``/``str``/
+    ``int``/``float``/``bool`` classes. ``Resource`` subclasses construct via
+    ``_from_payload`` (or constructible-from-scalar). Threads ``api``/``parent``
+    into every nested + list/dict element (``parent`` = the owning resource).
+
+    ``is_key`` marks this coercion as a resource's KEY field, threaded
+    through the Optional/Union/List/Dict recursion. A key keeps downcasting (so
+    ``'42'``/``42`` stay ==/hash-equal); a NON-key ``str`` field stops
+    downcasting non-strings (the truthiness-inversion backstop). It is NOT
+    propagated into a nested resource — that resource recomputes ``is_key`` for
+    its own key field.
+
+    Total/lenient: any unrecognized form or un-coercible value returns ``value``
+    unchanged — never raises.
+    """
+    if value is None:
+        return None
+
+    # Hot path: resolved resource field annotations are usually concrete scalar
+    # classes. Handle those before the slower typing-origin / issubclass probes.
+    if ann is str:
+        if isinstance(value, str):
+            return value
+        # Non-downcast backstop: a NON-key str field handed a non-str keeps it RAW (no
+        # ``str(False)=='False'`` truthiness inversion). Keys still downcast so
+        # ``'42'``/``42`` stay ==/hash-equal. Unconditional — no opt-out.
+        if not is_key:
+            return value
+        return str(value)
+    if ann is bool:
+        return _coerce_bool(value)
+    if ann in (int, float):
+        try:
+            return ann(value)
+        except (TypeError, ValueError, OverflowError):
+            # OverflowError: ``int(float('inf'))`` — stdlib json.loads admits
+            # Infinity/-Infinity/NaN, so a wire ``Infinity`` on a declared-int
+            # field reaches here. Degrade to raw (never raise on a scrape).
+            return value
+    if ann is datetime:
+        return _coerce_datetime(value)
+    if ann is Decimal:
+        return _coerce_decimal(value)
+
+    origin = get_origin(ann)
+
+    # Union / Optional — try each non-None arm; first that changes the value
+    # (or matches a resource/enum/special) wins. Optional[X] is X | None.
+    if origin in _UNION_ORIGINS:
+        args = [a for a in get_args(ann) if a is not type(None)]
+        # Single-arm Optional[X] → coerce as X.
+        if len(args) == 1:
+            return _coerce_by_annotation(value, args[0], api=api, parent=parent, is_key=is_key)
+        # Multi-arm union (e.g. ``Sort | str``): prefer an Enum/Resource arm
+        # (the precise type) over the bare str/scalar fallback; if none fire,
+        # fall through raw.
+        for arm in args:
+            if _is_enum_type(arm) or _is_resource_type(arm):
+                coerced = _coerce_by_annotation(value, arm, api=api, parent=parent, is_key=is_key)
+                # Accept the arm when it produced (or already was) an instance of
+                # it — an ``isinstance`` check, NOT object identity. (Identity
+                # would reject an already-coerced member, e.g. a ``Sort.NEW`` fed
+                # back through ``Sort | str``, then stringify it via the str arm.)
+                if isinstance(coerced, arm):
+                    return coerced
+        # No precise arm matched — coerce to the first arm (usually str) only if
+        # it's a primitive; else pass through.
+        for arm in args:
+            if arm in (str, int, float, bool, datetime, Decimal):
+                return _coerce_by_annotation(value, arm, api=api, parent=parent, is_key=is_key)
+        return value
+
+    # List[X] — envelope-unwrap a single-list dict, then recurse per element.
+    # This is the per-FIELD path (reached inside ``_from_payload`` on every
+    # ``List[X]`` field). It MUST stay lenient — degrade to raw, never raise —
+    # so one malformed nested list can't crash construction of a
+    # successfully-scraped resource and discard its other good fields. (Contrast
+    # the method-RETURN router ``coerce()``, which fails loud at its boundary.)
+    if origin in (list, List):
+        (inner,) = get_args(ann) or (Any,)
+        if isinstance(value, dict):
+            unwrapped = _unwrap_single_list(value)
+            if unwrapped is _NO_SINGLE_LIST:
+                return value  # lenient: keep the raw dict, never raise
+            value = unwrapped
+        if not isinstance(value, list):
+            return value
+        return [_coerce_by_annotation(v, inner, api=api, parent=parent, is_key=is_key) for v in value]
+
+    # Dict[K, V] — coerce values only (keys stay as-is).
+    if origin in (dict, Dict):
+        args = get_args(ann)
+        v_ann = args[1] if len(args) == 2 else Any
+        if not isinstance(value, dict):
+            return value
+        return {k: _coerce_by_annotation(v, v_ann, api=api, parent=parent, is_key=is_key)
+                for k, v in value.items()}
+
+    # Enum — member for an observed value, RAW for an unobserved-but-valid one
+    # (never raise). This is the divergence fix: a bare ``type: ContentType``
+    # field now coerces to the member at runtime instead of staying a str.
+    if _is_enum_type(ann):
+        if isinstance(value, ann):
+            return value
+        try:
+            return ann(value)  # exact wire-value match
+        except (ValueError, KeyError, TypeError):
+            pass
+        # Case-tolerant fallback (G7): the wire sometimes uppercases an enum
+        # value (``FOR_SALE`` for a ``for_sale`` member). Match str(value)
+        # against member values case-insensitively before giving up — using the
+        # same ``.lower()`` fold the codegen's code-uniqueness gate enforces, so
+        # a match is unambiguous. Keep raw on no match (never raise).
+        folded = str(value).lower()
+        for member in ann:
+            if str(member.value).lower() == folded:
+                return member
+        return value  # unobserved-but-valid → keep raw, never raise
+
+    # Resource — construct from a dict payload, or hydrate constructible from a
+    # bare scalar matching the keyed_by field.
+    if _is_resource_type(ann):
+        if isinstance(value, dict):
+            return ann._from_payload(value, api=api, parent=parent)
+        return _construct_from_scalar(ann, value, api=api, parent=parent)
+
+    # Any / unknown annotation form → raw passthrough (total/lenient).
+    return value
+
+
+def _is_enum_type(ann: Any) -> bool:
+    return isinstance(ann, type) and issubclass(ann, Enum)
+
+
+def _is_resource_type(ann: Any) -> bool:
+    return isinstance(ann, type) and issubclass(ann, Resource)
+
+
+def _resource_payload_meta(cls: "Type[Resource]") -> tuple:
+    """Cached per-class metadata used by ``Resource._from_payload``.
+
+    The generated class's annotations and ``_FIELD_ALIASES`` are fixed at module
+    import. Cache the derived wire-name map and consumed-wire set so high-volume
+    page hydration does not rebuild them for every row.
+
+    This is module-scoped on purpose: every new ``Resource`` member expands
+    codegen's reserved identifier set (``dir(Resource)``), which changes emitted
+    output for schemas that happen to use the same field name.
+    """
+    cached = cls.__dict__.get("_FIELD_HINTS_CACHE")
+    if (
+        isinstance(cached, tuple)
+        and len(cached) == 2
+        and isinstance(cached[0], dict)
+        and isinstance(cached[1], tuple)
+    ):
+        return cached[1]
+    hints = cls._field_hints()
+    aliases = cls._FIELD_ALIASES
+    wire_names = {name: aliases.get(name, name) for name in hints}
+    # Membership-tested only (in _from_payload's wrapper-unwrap probe); a
+    # frozenset dedupes aliases mapping to the same wire key and lets the probe
+    # be a set intersection rather than a per-element scan.
+    wires = frozenset(wire_names.values())
+    consumed = frozenset(hints) | frozenset(aliases.values()) | {"_api", "_parent"}
+    meta = (hints, wire_names, wires, consumed)
+    setattr(cls, "_FIELD_HINTS_CACHE", (hints, meta))
+    return meta
+
+
+# ---------------------------------------------------------------------------
+# Resource — base for every generated dataclass-like
+# ---------------------------------------------------------------------------
+
+
+class Resource:
+    """Base class for every generated resource (Post, Comment, Site, etc.).
+
+    Instances store their fields directly as attributes. ``_api`` is the
+    root client; ``_parent`` is the resource that exposed this one as a
+    sub-resource (for ``$self.parent.<field>`` references during method
+    calls). Fields are set by plain attribute assignment (``_extra`` carries
+    any undeclared wire fields). Instances are mutable by design — no attribute
+    interception is installed, so writes are ordinary.
+    """
+
+    _RESOURCE_NAME: ClassVar[str] = "Resource"
+    _KEY_FIELD: ClassVar[Optional[str]] = None
+    # Python-name → wire-name map (set by codegen from FieldSpec.alias_from).
+    # Lets a spec say ``created_at`` while the API returns ``created_utc``.
+    _FIELD_ALIASES: ClassVar[Dict[str, str]] = {}
+    # When True, this resource can be instantiated from just its key — used
+    # by the coerce() path when a nested field's payload is a bare scalar
+    # (e.g. ``post.subreddit = "smallbusiness"`` becomes ``Subreddit(name="smallbusiness")``).
+    _CONSTRUCTIBLE: ClassVar[bool] = False
+    # Resource class registry for the owning module. Codegen wires this up
+    # at module import time so the string-label return router (``coerce()``)
+    # can resolve a label like ``Post`` to its class.
+    _RESOURCE_REGISTRY: ClassVar[Dict[str, Type[Resource]]] = {}
+    # Per-class cache for resolved field annotations and derived payload metadata.
+    # Stored directly on each generated subclass (looked up via ``cls.__dict__``),
+    # not in a process-global dict: resolved annotations can reference sibling
+    # resource classes, and a global cache value would pin transient preview
+    # modules alive. A class-local cycle dies with the class/module graph. The
+    # slot name is pre-existing/runtime-reserved; payload metadata deliberately
+    # shares it so adding the optimization does not expand codegen's reserved
+    # member set (which is seeded from dir(Resource)).
+    _FIELD_HINTS_CACHE: ClassVar[Optional[Any]] = None
+
+    @classmethod
+    def _field_hints(cls) -> Dict[str, Any]:
+        """Resolved ``{field_name: type_object}`` for this class's own
+        annotated fields (the single per-field type source).
+
+        Uses ``get_type_hints(cls)`` with NO explicit ``globalns`` so forward
+        refs resolve in the *generated module's* namespace (where ``Sort`` /
+        ``Post`` live). Filters out ClassVars by ORIGIN (``get_origin is
+        ClassVar``) — not by name — because ``BaseAPI`` carries non-underscore
+        ClassVars and the runtime bases carry underscore ClassVars; both must
+        be excluded. Cached per class, resolved lazily. Never raises: a
+        resolution failure yields an empty hint map (the codegen gate makes
+        dangling refs impossible, but stay total).
+        """
+        cached = cls.__dict__.get("_FIELD_HINTS_CACHE")
+        if isinstance(cached, dict):
+            return cached
+        # The slot is shared with the ``(hints, meta)`` payload-meta form written
+        # by ``_resource_payload_meta``; recognise the SAME shape both readers
+        # write (don't diverge on a looser/stricter predicate).
+        if (
+            isinstance(cached, tuple)
+            and len(cached) == 2
+            and isinstance(cached[0], dict)
+            and isinstance(cached[1], tuple)
+        ):
+            return cached[0]
+        try:
+            raw_hints = get_type_hints(cls)
+        except Exception:  # noqa: BLE001 — total: never let resolution raise
+            raw_hints = {}
+        # Annotations declared on the runtime bases (Resource/object) are
+        # ClassVars; the per-resource fields are the plain annotations declared
+        # on the generated subclass. Filter ClassVars by origin.
+        #
+        # Flat-inheritance invariant: codegen emits ONLY ``class X(_Resource)``
+        # (single-level — there is no ``extends``/``base`` spec key), so the
+        # own-class ``__annotations__`` filter is correct-by-construction. An
+        # MRO walk would defend a multi-level shape the generator cannot
+        # produce, so we deliberately do NOT walk the MRO. (The codegen asserts
+        # this invariant when it emits each class.)
+        own = getattr(cls, "__annotations__", {})
+        hints: Dict[str, Any] = {}
+        for name, ann in raw_hints.items():
+            if name not in own:
+                continue  # inherited base annotation, not a resource field
+            if get_origin(ann) is ClassVar:
+                continue
+            hints[name] = ann
+        setattr(cls, "_FIELD_HINTS_CACHE", hints)
+        return hints
+
+    def __init__(self, *, _api: Optional[BaseAPI], _parent: Any = None, **fields: Any) -> None:
+        # Plain assignment — there is no ``__setattr__``/``__slots__`` override,
+        # so ``object.__setattr__`` was a no-op equal to ``self.x = v`` that
+        # implied a frozen contract the class doesn't enforce.
+        self._api = _api
+        self._parent = _parent
+        field_names = self._field_hints()
+        for name in field_names:
+            setattr(self, name, fields.get(name))
+        # Stash anything passed that isn't a declared field, under _extra, so
+        # the user can access surprise fields via ``obj._extra.get("weird")``
+        # without losing data.
+        self._extra = {k: v for k, v in fields.items() if k not in field_names}
+        # Advisory husk signal: count of declared fields whose RAW wire
+        # value was non-null. SET per-instance by ``_from_payload`` (a classmethod
+        # that builds ``inst`` directly), NOT here — this is an annotation-only
+        # declaration so pyright sees the instance attribute without us actually
+        # creating it. A bare ``self.x: int`` performs no assignment, so instances
+        # NOT built from a payload (e.g. coerce()'s key-only constructions) keep
+        # NO attribute, and the husk read ``getattr(inst, "_resolved_count", None)``
+        # still falls back to ``None`` for them (≠ 0 → not a husk). Declared here
+        # rather than as a class annotation so it stays OUT of ``_field_hints`` /
+        # ``get_type_hints`` and is never mistaken for a coercible wire field.
+        self._resolved_count: int
+
+    @classmethod
+    def _from_payload(
+        cls,
+        payload: Dict[str, Any],
+        *,
+        api: Optional[BaseAPI],
+        parent: Any = None,
+    ) -> Resource:
+        """Construct an instance from a raw response dict, coercing each
+        declared field by its resolved ANNOTATION (single source).
+        ``_FIELD_ALIASES`` lets a Python field name read from a different wire
+        key.
+
+        The instance is built first (with raw values), then each field is
+        coerced with ``parent`` set to THIS instance — so a nested resource's
+        ``_parent`` is the OWNING resource (active-record navigation), not the
+        grandparent. ``_api`` is threaded all the way down.
+        """
+        hints, wire_names, wires, consumed = _resource_payload_meta(cls)
+        # Wrapped-record unwrap — the single-RECORD analogue of
+        # ``_unwrap_single_list``. Detail APIs commonly nest the record under a
+        # wrapper key (``{"product": {...}}``, ``{"detail": {...}}``); a spec
+        # whose fields were typed from the INNER record would otherwise hydrate
+        # to an all-None husk (2026-06-09 corpus audit: 46/244 specs). Fires
+        # ONLY when (a) not one declared wire key resolves at the top level —
+        # so any legitimately-flat payload is untouched — and (b) exactly ONE
+        # dict-valued child contains at least one declared wire key (two
+        # matching children = ambiguous, leave raw rather than guess). When a
+        # wrapper is selected, sibling envelope metadata is still forwarded into
+        # _extra; only the structural wrapper key is dropped.
+        if isinstance(payload, dict) and payload and hints:
+            if not (wires & payload.keys()):
+                _cands = [(k, v) for k, v in payload.items()
+                          if isinstance(v, dict) and (wires & v.keys())]
+                if len(_cands) == 1:
+                    _wrapper, _wrapped = _cands[0]
+                    _outer_extra = {k: v for k, v in payload.items() if k != _wrapper}
+                    payload = {**_outer_extra, **_wrapped}
+        # Never forward a wire key literally named ``_api``/``_parent`` into
+        # raw_fields: it would collide with the explicit kwargs in
+        # ``cls(_api=..., _parent=..., **raw_fields)`` below and raise "multiple
+        # values for keyword argument". codegen reserves these as field
+        # identifiers, but an UNMAPPED wire key of that name would otherwise slip
+        # through the unknown-field forwarding — drop it.
+        raw_fields: Dict[str, Any] = {}
+        resolved_count = 0
+        for name in hints:
+            raw = payload.get(wire_names[name])
+            raw_fields[name] = raw
+            if raw is not None:
+                resolved_count += 1
+        # Forward unknown fields so _extra has them — but skip wire names that
+        # were already consumed via _FIELD_ALIASES (else we'd both set
+        # ``created_at`` AND leak ``created_utc`` into _extra).
+        for k, v in payload.items():
+            if k not in consumed:
+                raw_fields[k] = v
+        inst = cls(_api=api, _parent=parent, **raw_fields)
+        # Resolved-key signal (husk observation). Count the DECLARED fields
+        # whose post-unwrap raw wire value is non-null — the husk verdict in
+        # coerce() reads this instead of re-running the wrapped-record unwrap.
+        # It is a private instance attribute, set on EVERY constructed instance,
+        # and is purely advisory: _from_payload itself NEVER raises on it (the
+        # verdict lives in coerce(), which is NOT shared with the lenient
+        # per-field router). Computed from the RAW wire values (pre-coercion) so
+        # a lenient coercion that degrades a value to None can't mask a key that
+        # the wire actually resolved.
+        inst._resolved_count = resolved_count
+        # Coerce annotated fields now that the owning instance exists, threading
+        # it as the parent of every nested + list/dict element. Plain assignment
+        # (no __setattr__ override to bypass).
+        key_field = cls._KEY_FIELD
+        for name, ann in hints.items():
+            coerced = _coerce_by_annotation(raw_fields[name], ann, api=api, parent=inst,
+                                            is_key=(name == key_field))
+            setattr(inst, name, coerced)
+        return inst
+
+    def __repr__(self) -> str:
+        key = self._KEY_FIELD
+        if key and hasattr(self, key):
+            return f"{type(self).__name__}({key}={getattr(self, key)!r})"
+        return f"{type(self).__name__}(...)"
+
+    def _identity_key(self) -> Any:
+        """The hashable identity value and its hash, or ``None`` when this instance has no
+        usable identity: no ``_KEY_FIELD``; a null key value (a null never
+        asserts identity — two null-keyed instances are NOT the same record);
+        or an unhashable container that leaked into the key field through
+        lenient coercion. ``__eq__`` and ``__hash__`` both route through this
+        single source so they can never disagree, and ``__hash__`` can reuse
+        the hashability probe instead of calling ``hash(val)`` twice."""
+        key = self._KEY_FIELD
+        if not key:
+            return None
+        val = getattr(self, key, None)
+        if val is None:
+            return None
+        try:
+            val_hash = hash(val)
+        except TypeError:
+            return None
+        return val, val_hash
+
+    def __eq__(self, other: Any) -> bool:
+        if not isinstance(other, type(self)):
+            return NotImplemented
+        mine = self._identity_key()
+        theirs = other._identity_key()
+        if mine is None or theirs is None:
+            return self is other
+        return mine[0] == theirs[0]
+
+    def __hash__(self) -> int:
+        identity = self._identity_key()
+        if identity is None:
+            return id(self)
+        return hash((type(self).__name__, identity[1]))
+
+
+# ---------------------------------------------------------------------------
+# Collection — typed namespace for sub-resources (`site.subareas`, `reddit.posts`)
+# ---------------------------------------------------------------------------
+
+
+class Collection:
+    """A typed handle on a sub-resource or top-level resource collection.
+
+    The codegen subclasses this per collection so static type checkers see
+    typed ``.get(...)`` / ``.list(...)`` etc. methods. The runtime base
+    just holds the API + parent references.
+    """
+
+    def __init__(self, _api: BaseAPI, _parent: Any = None) -> None:
+        self._api = _api
+        self._parent = _parent
+
+
+# ---------------------------------------------------------------------------
+# Paginator — auto-paging iterator returned by `paginates`-tagged operations
+# ---------------------------------------------------------------------------
+
+
+_PaginatorItem = TypeVar("_PaginatorItem")
+
+
+def _resource_content_projection(it: "Resource") -> Any:
+    """A STABLE, hashable content signature for a keyless / null-keyed
+    ``Resource`` — the runtime fix for the keyless ``_page_signature`` churn.
+
+    A keyless ``Resource`` (``_KEY_FIELD = None``) hashes by ``id(self)``, so the
+    historical signature churned and the content-stall guard NEVER matched a
+    keyless full-page repeat across pages. Two DISTINCT objects carrying the SAME
+    wire content must project EQUAL so the guard can see that repeat; two
+    genuinely-different keyless rows must project differently (no false trigger).
+
+    Content is mined from the resource's declared fields (the single per-class
+    source) + any undeclared wire data in ``_extra``, sorted by name so dict
+    order can't perturb the projection. Each value is taken verbatim when
+    hashable, else rendered to a stable JSON string (``sort_keys``) so an
+    unhashable list/dict field can't break signing; an exotic value falls back
+    to ``repr``. The result is ALWAYS hashable — a keyless Resource therefore
+    always signs (it never forces the whole page to ``None``).
+
+    Scope is deliberately KEYLESS RESOURCES ONLY: a raw dict/list passthrough
+    keeps the historical "unhashable → page unsignable → ``None``" behavior in
+    ``_page_signature`` (no content-stall compare), so a heterogeneous
+    keyed-then-raw page stream still terminates at ``max_fetches`` rather than
+    newly raising — preserving cross-compat for every already-generated module."""
+    def _stable(v: Any) -> Any:
+        # A NESTED Resource value must canonicalize by its CONTENT, not be
+        # returned verbatim: a keyless Resource hashes by ``id(self)`` (so the
+        # ``hash(v)`` probe below would succeed and return the churning instance),
+        # which made a keyless value-object field churn across pages and left the
+        # content-stall guard ineffective for nested-value-object shapes (codex
+        # P2). Recurse into its content projection instead. A list/tuple is
+        # canonicalized element-wise so a ``List[Resource]`` value-object field
+        # canonicalizes too; raw dict/list (non-Resource) keeps the historical
+        # json.dumps passthrough below.
+        if isinstance(v, Resource):
+            return _resource_content_projection(v)
+        if isinstance(v, (list, tuple)):
+            return tuple(_stable(x) for x in v)
+        try:
+            hash(v)
+            return v
+        except TypeError:
+            pass
+        try:
+            return json.dumps(v, sort_keys=True, default=str)
+        except (TypeError, ValueError):
+            return repr(v)
+
+    fields = it._field_hints()
+    parts: List[tuple] = [(name, _stable(getattr(it, name, None))) for name in fields]
+    extra = getattr(it, "_extra", None)
+    if isinstance(extra, dict):
+        parts += [(f"_extra:{k}", _stable(v)) for k, v in extra.items()]
+    return ("R", type(it).__name__, tuple(sorted(parts)))
+
+
+def _page_signature(items: Iterable[Any]) -> Optional[tuple]:
+    """An ordered tuple of per-item identity signals for one page, or ``None``
+    if the page can't be signed.
+
+    Each item's signal is its ``_KEY_FIELD`` value when the item is a keyed
+    ``Resource``; a keyless / null-keyed ``Resource`` signs by a STABLE CONTENT
+    PROJECTION (:func:`_resource_content_projection`) instead of the historical
+    ``id(self)`` churn — so the content-stall guard can now catch a keyless
+    full-page repeat (two pages of distinct-object-but-same-content keyless rows
+    project EQUAL; genuinely-different keyless content projects differently, no
+    false trigger). A NON-Resource item (raw dict / list / scalar passthrough)
+    keeps the historical rule: hashable → the item itself; unhashable → the
+    whole page is unsignable and we return ``None`` (the caller skips the
+    content-stall compare). That scope keeps a heterogeneous keyed-then-raw
+    stream cross-compatible — a raw-dict page still never signs, so it can't
+    newly raise on an already-generated module.
+
+    Ordered (not a set) so a reordered page reads as different — the strictest
+    same-page signal. For KEYED items the signal is the key only (never full
+    content) so volatile non-key fields (vote counts, timestamps) can't mask a
+    stall; for KEYLESS RESOURCES full content is the only available identity, so
+    the documented residual stands: a keyless feed whose entire page genuinely
+    re-appears within the recent-signature window reads as a stall (the error
+    names the ``max_fetches=`` override).
+    """
+    sig: List[Any] = []
+    for it in items:
+        kf = getattr(type(it), "_KEY_FIELD", None)
+        if kf:
+            # A KEYED Resource: sign by its key value when present. A NULL key on
+            # this page (key only on detail responses, or an alias mis-mapping)
+            # keeps the historical id-hash behavior — two pages of DISTINCT
+            # null-keyed-on-list records must NOT collapse to one signature and
+            # false-stall (``test_null_keyed_pages_do_not_false_stall``). The
+            # content-projection fix is scoped to GENUINELY KEYLESS resources
+            # below, where id-hash actively hid a real repeat; a keyed-but-
+            # null-on-this-page record is a distinct record whose key simply
+            # isn't on the list page — the cross-compat shape we must not regress.
+            key = getattr(it, kf, None)
+            if key is not None:
+                sig.append(key)
+                continue
+            try:
+                hash(it)
+            except TypeError:
+                return None
+            sig.append(it)
+            continue
+        if isinstance(it, Resource):
+            # Keyless Resource (``_KEY_FIELD is None``): sign by stable content so
+            # a keyless full-page repeat is visible to the stall guard (the
+            # fix — id-hash churned and hid it). Distinct keyless content still
+            # projects differently; the accepted residual is a genuinely
+            # content-identical keyless full page reading as a stall.
+            sig.append(_resource_content_projection(it))
+            continue
+        # Non-Resource passthrough (raw dict/list/scalar) — historical rule:
+        # hashable → the item; unhashable → whole page unsignable (``None``).
+        try:
+            hash(it)
+        except TypeError:
+            return None
+        sig.append(it)
+    return tuple(sig)
+
+
+class Paginator(Generic[_PaginatorItem]):
+    """Iterator that fetches more pages as the user consumes them.
+
+    Build kwargs contain the original method args; ``_fetch_page`` returns
+    ``(items, next_cursor)``. Iteration stops when ``next_cursor`` is None
+    or the user breaks. Cap by passing ``limit=`` at call time — the
+    paginator will short-circuit once that many items have been yielded.
+
+    Generic so codegen can emit ``Paginator[Listing]`` / ``Paginator[Post]``
+    return annotations. Without that, ``for listing in api.listings.search()``
+    widens ``listing`` to ``Any`` and pyright loses all field-access
+    intelligence — defeating the whole point of the typed SDK.
+
+    **Stall safety.** Two disjoint terminators stop a runaway paginator
+    (a server that re-returns the same page because its pagination contract
+    was mis-derived):
+
+      * a **content-stall guard** — measures progress by the *data* (an
+        ordered tuple of per-item keys). When a non-empty page repeats ANY of
+        the last 4 page signatures it raises :class:`PaginationLimitError` —
+        so a same-page stall dies on the 2nd fetch and a short-period cycle
+        (the realistic mis-derived page/offset oscillation) on the 3rd-5th,
+        instead of burning the full billable fetch budget. Cursor-agnostic
+        (the SDK fabricates an advancing cursor for token-less servers, so
+        the cursor is useless as a progress signal); unsignable pages
+        (raw-dict passthrough) are simply invisible to it, never a false
+        trigger. Residual false-positive shape: a burst of ≈k·page_size new
+        items landing between two fetches of an offset-paginated moving feed
+        can make page N+k repeat page N's keys exactly — rare, and the error
+        names the ``max_fetches=`` override an agent can act on.
+      * a **``max_fetches`` iteration bound** — the sole terminator for the
+        cases the content guard cannot see (slow-crawl, unhashable streams,
+        cycles with period > 4). User-overridable; raise it for legitimate
+        deep pagination.
+
+    These cover *disjoint* failure modes — not two layers over one. A
+    previously-hanging paginator now *raises* instead; this terminal outcome
+    applies to already-rendered modules on a runtime bump (they import
+    ``Paginator`` from here) without regeneration. The ``max_fetches`` arm
+    also raises on a *legitimately-completing* result set that exceeds the
+    budget (not only hanging ones) — an unbounded ``.list()`` over >1000 pages
+    must pass a larger ``max_fetches=``; the error message names the override.
+
+    **Window exhaustion.** A third terminator covers the upstream's own result
+    window: a mid-stream 4xx (after ≥1 successful page, excluding 429
+    backpressure) means the site refuses deeper pages — e.g. GitHub search
+    serves at most 1000 results regardless of ``total``. That raises
+    :class:`PaginationLimitError` (with the ``UpstreamError`` as ``__cause__``)
+    rather than stopping silently: yielded items are valid, but treating a cap
+    as "the result set ends here" would hand the consumer a wrong-data
+    conclusion. First-fetch errors and 5xx/network failures surface raw.
+    """
+
+    def __init__(
+        self,
+        fetch_page: Callable[[Optional[Any]], "tuple[List[_PaginatorItem], Optional[Any]]"],
+        *,
+        limit: Optional[int] = None,
+        max_fetches: int = 1000,
+        dedup: bool = False,
+        identity_dedup: bool = False,
+        _api: Optional[Any] = None,
+    ) -> None:
+        # Validate here, not in __next__: the constructor is the single
+        # chokepoint every generated op routes through, and a bad kwarg must
+        # fail at the call site that supplied it — not pages later inside
+        # iteration with a bare comparison TypeError. bool is excluded
+        # explicitly (it passes isinstance(int) but `limit=True` is a bug).
+        if limit is not None and (not isinstance(limit, int) or isinstance(limit, bool)):
+            raise TypeError(
+                f"limit must be an int or None, got {limit!r} ({type(limit).__name__})"
+            )
+        if limit is not None and limit < 1:
+            raise ValueError(f"limit must be >= 1, got {limit!r}")
+        if not isinstance(max_fetches, int) or isinstance(max_fetches, bool):
+            raise TypeError(
+                f"max_fetches must be an int, got {max_fetches!r} ({type(max_fetches).__name__})"
+            )
+        if max_fetches < 1:
+            raise ValueError(f"max_fetches must be >= 1, got {max_fetches!r}")
+        # identity_dedup is the raw-page-signature arm layered ON TOP of dedup
+        # (consumed only inside ``if self._dedup:`` in __next__). Passing it with
+        # dedup=False would silently no-op the entire stall-guard, so reject the
+        # combination here rather than let the flag be invisibly inert at runtime.
+        if identity_dedup and not dedup:
+            raise ValueError("identity_dedup=True requires dedup=True")
+        self._fetch_page = fetch_page
+        self._api = _api  # owning client, for last_meta passthrough
+        self._limit = limit
+        self._max_fetches = max_fetches
+        # dedup-by-identity: a scheme that can re-serve overlapping items across
+        # pages (time_cursor's inclusive-boundary re-seed; a page/cursor op on a
+        # moving feed). The next request re-seeds and the boundary/overlap items
+        # repeat and would be yielded twice — the content-stall guard only catches
+        # WHOLE-page repeats, not partial overlap. With dedup on, items already
+        # seen (by their _Resource identity / _KEY_FIELD) are dropped, and a
+        # NON-EMPTY page contributing 0 NEW items terminates gracefully —
+        # generalizing the content-stall guard and killing the infinite re-seed.
+        #
+        # F-2 carve-out: a genuinely EMPTY raw page (0 server rows) with a still-
+        # advancing cursor is NOT a 0-new terminus — it is an interstitial gap
+        # that gets RE-FETCHED (matching the non-dedup path), so a single empty
+        # interstitial page no longer silently truncates every page after it. The
+        # 0-new STOP fires only for a NON-empty page whose every row is already
+        # seen (the inclusive-boundary re-seed). See ``__next__``.
+        #
+        # F-3 accepted residual (dedup WITHOUT server cooperation): when the
+        # server's cursor keeps advancing on a NON-empty page whose rows are all
+        # already-seen overlap, the SDK cannot tell that 0-new terminus apart
+        # from a transient overlap that a LATER page would break — both look
+        # identical at the moment of decision (the server gives no end signal).
+        # We take the 0-new STOP (the only contract that terminates the infinite
+        # inclusive-boundary re-seed); a feed that re-serves a fully-overlapping
+        # page mid-stream and only then advances to fresh rows is the documented
+        # residual. It is bounded and safe (it never yields wrong data — it can
+        # only under-read), and a consumer who needs the deeper rows passes a
+        # wider window via a larger ``max_fetches`` on the non-dedup path. Not
+        # over-engineered with a speculative look-ahead.
+        self._dedup = dedup
+        # identity_dedup: the page/cursor identity-dedup arm (the
+        # sample-proven-unique ops) adds the raw-page-signature raise/terminate
+        # rule ON TOP of dedup — BEFORE deduping, a RAW page whose signature
+        # repeats a recent one is a genuine re-served page → raise
+        # PaginationLimitError; a 0-fresh-after-dedup page whose raw signature is
+        # NOVEL is a natural overlap-boundary end → StopIteration. time_cursor
+        # emits ``dedup=True`` ALONE (``identity_dedup`` defaults False), so it
+        # keeps its graceful 0-new stop unchanged — and every ALREADY-GENERATED
+        # time_cursor module (which passes only ``dedup=True``) is behavior- and
+        # byte-stable on a runtime bump (the new flag is opt-in, default-off).
+        self._identity_dedup = identity_dedup
+        self._seen: set = set()
+        self._yielded = 0
+        self._fetches = 0
+        self._cursor: Optional[Any] = None
+        self._buffer: deque[_PaginatorItem] = deque()
+        # Last 4 page signatures (not just the previous one): membership is a
+        # linear ``in`` over ≤4 tuples — signatures may hold unhashable key
+        # values, so a set is not an option (and is not needed at this size).
+        self._recent_sigs: "deque[tuple]" = deque(maxlen=4)
+        self._done = False
+
+    @property
+    def pages_fetched(self) -> int:
+        """Number of pages fetched from the wire so far."""
+        return self._fetches
+
+    @property
+    def items_yielded(self) -> int:
+        """Number of items yielded to the caller so far."""
+        return self._yielded
+
+    @property
+    def exhausted(self) -> bool:
+        """True once iteration has terminated (no more pages)."""
+        return self._done
+
+    @property
+    def last_meta(self) -> Optional["RequestMeta"]:
+        """Control-loop metadata from the owning client's most recent page."""
+        return getattr(self._api, "last_meta", None)
+
+    def __iter__(self) -> "Paginator[_PaginatorItem]":
+        return self
+
+    def __next__(self) -> _PaginatorItem:
+        if self._limit is not None and self._yielded >= self._limit:
+            raise StopIteration
+        while not self._buffer:
+            if self._done:
+                raise StopIteration
+            if self._fetches >= self._max_fetches:
+                raise PaginationLimitError(
+                    f"pagination exceeded max_fetches={self._max_fetches} — likely a "
+                    f"mis-derived pagination contract, or raise max_fetches= for "
+                    f"legitimate deep pagination",
+                    pages_fetched=self._fetches, items_yielded=self._yielded,
+                )
+            try:
+                items, next_cursor = self._fetch_page(self._cursor)
+            except UpstreamError as err:
+                # Window-exhaustion classification. A mid-stream upstream 4xx —
+                # the same params that already succeeded N times, refused one
+                # cursor deeper — is a data boundary (a result-window cap, e.g.
+                # GitHub search caps at 1000), not a transient failure: raise
+                # the typed pagination error with the evidence chained, never
+                # a raw UpstreamError after minutes of valid iteration.
+                # Carve-outs, both deliberate:
+                #   * first fetch (_fetches == 0) never classifies — a param/
+                #     auth error must surface exactly as on a non-paginated op;
+                #   * upstream 429 is backpressure, not a boundary — classify-
+                #     ing it would tell the consumer the result set ends here
+                #     (the wrong-data failure this design exists to prevent).
+                #     The SDK's retry machinery covers only GATEWAY 429s, so
+                #     the upstream-429-in-502-envelope surfaces raw.
+                # A genuine page-N-only 4xx is indistinguishable from a window
+                # cap; after N identical-param successes the boundary is the
+                # correct bet, and __cause__ preserves the evidence either way.
+                usc = err.upstream_status_code
+                if (
+                    self._fetches >= 1
+                    and isinstance(usc, int)
+                    and 400 <= usc < 500
+                    and usc != 429
+                ):
+                    raise PaginationLimitError(
+                        f"upstream result window exhausted after "
+                        f"{self._yielded} items / {self._fetches} pages "
+                        f"(upstream HTTP {usc}); items already yielded are "
+                        f"valid — catch PaginationLimitError or pass limit= "
+                        f"to bound the scan",
+                        pages_fetched=self._fetches, items_yielded=self._yielded,
+                    ) from err
+                raise
+            self._fetches += 1
+            self._buffer = deque(items or [])
+            self._cursor = next_cursor
+            if next_cursor is None:
+                self._done = True
+            if self._dedup:
+                # Whether the server returned an EMPTY page (0 raw rows) — distinct
+                # from a non-empty page that DEDUPS to 0 fresh. An empty raw page
+                # with an advancing cursor is an interstitial gap that must be
+                # RE-FETCHED (the non-dedup path does so via the `while not
+                # self._buffer` loop below); only a non-empty page whose every row
+                # is already seen is the inclusive-boundary 0-new terminus. F-2:
+                # the old dedup arm conflated the two and stopped on the empty
+                # interstitial page, silently dropping every page after it.
+                _raw_empty = not self._buffer
+                if self._identity_dedup:
+                    # raw-page-signature raise/terminate (page/cursor identity
+                    # dedup only — time_cursor keeps its graceful 0-new stop).
+                    # Sign the RAW (pre-dedup) page and reuse the SAME _recent_sigs
+                    # the content-stall guard owns: a raw page whose signature
+                    # repeats a recent one is a GENUINE re-served page (the cursor
+                    # stalled) → raise, exactly as the non-dedup content guard
+                    # already does for a repeated non-empty page. A 0-fresh page
+                    # whose raw signature is NOVEL is a natural overlap-boundary
+                    # end → falls through to the graceful 0-new stop below. (An
+                    # EMPTY raw page signs as the empty tuple `()`; guarding the
+                    # raise on `_raw_sig` truthiness keeps a bare interstitial
+                    # empty page from ever being mis-read as a re-served page.)
+                    _raw_sig = _page_signature(self._buffer)
+                    if _raw_sig:
+                        if _raw_sig in self._recent_sigs:
+                            raise PaginationLimitError(
+                                "pagination stalled — the server re-served the same "
+                                "page of items before dedup; likely a mis-derived "
+                                "pagination contract, or raise max_fetches= for "
+                                "legitimate deep pagination",
+                                pages_fetched=self._fetches, items_yielded=self._yielded,
+                            )
+                        self._recent_sigs.append(_raw_sig)
+                # Drop items already seen (by _Resource identity / _KEY_FIELD; a
+                # _KEY_FIELD=None resource hashes by id(self) → never collides, so
+                # no data loss). A non-empty page contributing 0 NEW items
+                # terminates gracefully — this supersedes the content-stall check
+                # on the time_cursor path (it handles PARTIAL overlap, which the
+                # whole-page stall guard cannot). max_fetches stays the backstop.
+                fresh: List[_PaginatorItem] = []
+                for it in self._buffer:
+                    if isinstance(it, Resource):
+                        # Dedup on the identity TOKEN, not the instance — the
+                        # set otherwise retains every yielded Resource (full
+                        # payload) for the whole iteration. ``_identity_key``
+                        # is the single equality source: when it is None (no
+                        # key field / null key / unhashable key) the instance
+                        # has no identity and membership could never fire
+                        # (id-hash vs fresh objects), so skip dedup for it —
+                        # observationally identical, retention dropped.
+                        idk = it._identity_key()
+                        if idk is not None:
+                            token = (type(it), idk[0])
+                            if token in self._seen:
+                                continue
+                            self._seen.add(token)
+                        fresh.append(it)
+                        continue
+                    try:
+                        if it in self._seen:
+                            continue
+                        self._seen.add(it)
+                    except TypeError:
+                        pass  # unhashable item → never deduped (fall back to bounds)
+                    fresh.append(it)
+                self._buffer = deque(fresh)
+                if not self._buffer:
+                    if _raw_empty:
+                        # The RAW page was empty — an interstitial gap, NOT the
+                        # inclusive-boundary terminus. Re-fetch if the cursor is
+                        # still live (the non-dedup behavior); stop only when the
+                        # cursor itself ended (`self._done`). Bounded by
+                        # max_fetches above, exactly like the non-dedup empty-page
+                        # path. This is the F-2 data-loss fix.
+                        if self._done:
+                            raise StopIteration
+                        continue
+                    # A NON-EMPTY page that dedups to 0 fresh items: a fully-seen
+                    # re-seed (inclusive boundary). Stop — re-fetching would
+                    # re-seed the same cursor identically (infinite loop). This is
+                    # time_cursor's graceful 0-new terminus.
+                    self._done = True
+                    raise StopIteration
+                continue  # dedup path owns its own termination; skip stall guard
+            if not self._buffer:
+                if self._done:
+                    raise StopIteration
+                # else: empty page but more cursors — re-fetch (bounded by
+                # max_fetches above; excluded from the content compare so a
+                # fabricated-cursor empty-page re-fetch isn't misclassified).
+                continue
+            # Content-stall guard — recomputed per page (no cached capability
+            # flag). Only compares when the page is signable; an unsignable
+            # page leaves the window untouched (appending a None would let a
+            # later None == None false-trigger on a legit stream). Matching
+            # ANY of the last 4 signatures catches the same-page stall (lag 1)
+            # AND the short-period cycle (a mis-derived page/offset contract
+            # oscillating between pages) at fetch ~3 instead of burning the
+            # whole max_fetches budget of billable requests.
+            sig = _page_signature(self._buffer)
+            if sig is not None:
+                if sig in self._recent_sigs:
+                    raise PaginationLimitError(
+                        "pagination stalled — the server re-returned the same page "
+                        "of items; likely a mis-derived pagination contract, or raise "
+                        "max_fetches= for legitimate deep pagination",
+                        pages_fetched=self._fetches, items_yielded=self._yielded,
+                    )
+                self._recent_sigs.append(sig)
+        v = self._buffer.popleft()
+        self._yielded += 1
+        return v
+
+    def list(self) -> List[_PaginatorItem]:
+        """Materialize all pages into a list. Convenient when you know the
+        result set is small. Respects the ``limit`` cap.
+
+        On a :class:`PaginationLimitError` the items collected so far are
+        attached as ``err.partial_items`` before the error propagates — the
+        materialized prefix is valid data and must not vanish with the raise.
+        (Raw ``list(paginator)`` / comprehensions cannot offer this carry;
+        prefer ``.list()``.)"""
+        out: List[_PaginatorItem] = []
+        try:
+            for v in self:
+                out.append(v)
+        except PaginationLimitError as err:
+            err.partial_items = list(out)
+            raise
+        return out
+
+    def first(self) -> Optional[_PaginatorItem]:
+        """Return the first item or None. Stops paging after that item."""
+        for v in self:
+            return v
+        return None
+
+
+# ---------------------------------------------------------------------------
+# BaseAPI — root client class
+# ---------------------------------------------------------------------------
+
+
+class BaseAPI:
+    """Base class for every generated root client (Reddit, Craigslist, ...).
+
+    Per-API subclasses set ``SCRAPER_ID`` and expose top-level resource
+    collections / methods. The base handles auth, transport, error
+    classification, and the executor's response-envelope unwrap.
+    """
+
+    SCRAPER_ID: ClassVar[str] = ""
+    # Pinned snapshot version for a locally-added MARKETPLACE canonical: codegen
+    # bakes this onto the generated client (from the `[tool.parse].marketplace`
+    # entry's recorded version) so every call sends ``API-Snapshot-Version: N``
+    # and the executor serves that exact release — the contract stays frozen even
+    # as the canonical self-heals. None for owned/account APIs (track latest).
+    PINNED_VERSION: ClassVar[Optional[int]] = None
+    # Generated clients override with ``{wire_kind: GeneratedErrorClass}`` for
+    # every ErrorSpec that declared a ``code``; empty here so the base + any
+    # client without declared error codes falls through to the HTTP-status table.
+    _ERROR_CLASSES: ClassVar[Dict[str, type]] = {}
+
+    # Retry defaults: low (an agent must SEE backpressure, not be silently
+    # blocked behind a long backoff chain), and bounded — a retry re-runs a
+    # billable scrape, so only safe (GET/HEAD) requests are ever retried.
+    _DEFAULT_MAX_RETRIES: ClassVar[int] = 1
+    _RETRY_MAX_BACKOFF: ClassVar[float] = 30.0    # per-retry ceiling (s)
+    _RETRY_TOTAL_BUDGET: ClassVar[float] = 60.0   # total-elapsed cap (s)
+    _RETRY_BASE_BACKOFF: ClassVar[float] = 0.5    # exponential base (s)
+    _RETRY_SAFE_METHODS: ClassVar[frozenset] = frozenset({"GET", "HEAD"})
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 60.0,
+        *,
+        max_retries: Optional[int] = None,
+    ) -> None:
+        # Store the key (which may be None) WITHOUT raising — keyless
+        # construction is allowed for offline / typed-only introspection
+        # (``Root()`` to read the modeled surface without a key). The
+        # runtime-safety raise moves to the first ``_request`` call.
+        # Route construction through config.resolve() so `parse login`
+        # (which writes ~/.config/parse/credentials) authenticates scripts,
+        # not just the CLI. resolve() chains kwarg → PARSE_API_KEY env →
+        # credentials file → default base_url (the KEY has no default).
+        # Keyless construction still succeeds; the AuthError stays lazy in
+        # _request. Do NOT call require_key() here — wrong type, and it would
+        # break offline/keyless introspection.
+        import httpx  # lazy (see plan 003) — a dict lookup after first use
+
+        cfg = _resolve_config(api_key, base_url)
+        self._api_key = cfg.api_key            # may be None
+        # OAuth access token from `parse login --web` (host-gated by resolve()).
+        # Used as a Bearer when no api_key is present; the api_key path is
+        # unchanged. Long-running scripts on a web-login token must re-login
+        # after the ~1h token lifetime (the CLI refreshes proactively; the
+        # runtime does not).
+        self._access_token = cfg.access_token  # may be None
+        self._base_url = cfg.base_url          # already rstrip'd, defaulted
+        self._timeout = timeout
+        # A bare float fans out to all four httpx timeout classes — fine for
+        # read/write/pool (slow scrapes are legitimate), wrong for CONNECT:
+        # TCP connect to the API host either succeeds in milliseconds or the
+        # host is unreachable, and a blackholed route would stall an agent the
+        # full 60s before the (good) network-error message appears. Bound
+        # connect; a per-request ``timeout=`` override REPLACES all four
+        # (httpx semantics), which callers opting in accept.
+        self._client = httpx.Client(
+            timeout=httpx.Timeout(timeout, connect=min(timeout, 10.0))
+        )
+        # Control-loop metadata from the most recent SUCCESSFUL response. Read
+        # after a call to self-pace on credits/quota; on an error read err.meta
+        # instead (last_meta stays on the last success, by design). Semantics
+        # under a BaseAPI shared across threads: last-write-wins. The assignment
+        # is atomic (GIL), but a reader may observe a concurrent request's meta —
+        # for per-call metadata under sharing, use err.meta / the call's result
+        # rather than this convenience attribute.
+        self.last_meta: Optional[RequestMeta] = None
+        # Retry knobs: ``max_retries`` is per-instance (a constructor kwarg);
+        # the backoff ceiling / total budget / base are CLASS consts read via
+        # ``self.`` so a subclass can override them. The dead per-instance
+        # copies of the latter two are gone — nothing exposed a setter, and the
+        # base const was already read off the class, so they were asymmetric
+        # no-ops.
+        self._max_retries = self._DEFAULT_MAX_RETRIES if max_retries is None else max(0, int(max_retries))
+
+    def __enter__(self) -> BaseAPI:
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._client.close()
+
+    # --- HTTP -------------------------------------------------------------
+
+    def _serialize_param(self, v: Any) -> Any:
+        """Normalize a Python value into something the wire can carry."""
+        if v is None:
+            return None
+        # Coerce enum members to their wire codes (Enum imported module-top).
+        if isinstance(v, Enum):
+            # If the enum value is itself meaningful (str/int), use it; else fall back to .name
+            inner = v.value
+            return inner if isinstance(inner, (str, int, float, bool)) else v.name
+        if isinstance(v, datetime):
+            return v.isoformat()
+        if isinstance(v, Decimal):
+            return str(v)
+        if isinstance(v, Resource):
+            # Reference by key if available, else raise — won't serialize a whole instance
+            key = type(v)._KEY_FIELD
+            if key and hasattr(v, key):
+                return getattr(v, key)
+            raise TypeError(f"cannot serialize {type(v).__name__} without a keyed_by field")
+        # Recurse into containers so a List[datetime] / List[Decimal] / List[Resource]
+        # (or dict thereof) — shapes codegen itself emits for params — has its
+        # elements normalized too, instead of hard-crashing at json.dumps(v).
+        if isinstance(v, (list, tuple)):
+            return [self._serialize_param(x) for x in v]
+        if isinstance(v, dict):
+            return {k: self._serialize_param(x) for k, x in v.items()}
+        return v
+
+    def _retry_sleep(self, seconds: float) -> None:
+        """Sleep before a retry. Isolated so tests can record (not wait)."""
+        time.sleep(seconds)
+
+    def _retry_backoff(self, attempt: int, retry_after: Optional[int]) -> float:
+        """Backoff seconds for ``attempt`` (1-based).
+
+        When the server gives an explicit ``retry_after``, HONOR it as a floor
+        (sleep at least that long) plus a small jitter to de-synchronize retry
+        storms — then cap to the per-retry ceiling (the server could return an
+        absurd value like an hour; the ceiling guarantees we never sleep that
+        long). With no server signal, use exponential backoff with full jitter.
+        """
+        if retry_after is not None and retry_after > 0:
+            # Honor the server's hint as a floor (capped), + up to 1s jitter.
+            base = min(float(retry_after), self._RETRY_MAX_BACKOFF)
+            jitter = random.uniform(0, min(1.0, max(0.0, self._RETRY_MAX_BACKOFF - base)))
+            return base + jitter
+        # No server signal — exponential backoff with full jitter in [0, target].
+        target = min(self._RETRY_BASE_BACKOFF * (2 ** (attempt - 1)), self._RETRY_MAX_BACKOFF)
+        return random.uniform(0, target) if target > 0 else 0.0
+
+    def _request(
+        self,
+        method: str,
+        endpoint_name: str,
+        params: Dict[str, Any],
+        *,
+        timeout: Optional[float] = None,
+    ) -> Any:
+        """Hit ``/scraper/<SCRAPER_ID>/<endpoint_name>`` with the given params.
+
+        Returns the unwrapped payload (the contents of ``data`` when the
+        scraper used the ``ScraperResult.success`` envelope, else the raw
+        body). Raises a ``ParseError`` subclass for non-2xx responses.
+
+        ``timeout`` overrides the client-construction timeout for THIS request
+        only (httpx supports a per-request timeout) — no new client needed.
+
+        On a 429 for a SAFE method (GET/HEAD), retries up to ``max_retries``
+        times with exponential backoff + jitter, honoring the server's
+        ``Retry-After`` header (capped to a ceiling + a total-elapsed budget).
+        A POST 429 is NEVER retried — a retry re-runs a billable,
+        non-idempotent scrape. When retries are exhausted the final
+        ``RateLimitError`` surfaces unchanged so an agent still sees
+        backpressure.
+        """
+        import httpx  # lazy (see plan 003) — a dict lookup after first use
+
+        # Lazy-auth guard: a keyless client constructs fine (offline
+        # introspection) but a real request needs a key. Raise BEFORE building
+        # headers / touching transport so we never send ``X-API-Key: None``.
+        # The key is RE-DERIVED through the host gate at this header site (not
+        # only at __init__) so the sink stays correct-by-construction even if a
+        # future refactor mutates ``_base_url`` after construction.
+        trusted = _host_is_trusted(self._base_url)
+        key = self._api_key if trusted else None
+        token = self._access_token if trusted else None
+        if not key and not token:
+            if not trusted:
+                raise AuthError(
+                    0,
+                    f"Parse API requests to {self._base_url!r} cannot carry credentials — "
+                    f"it is not a trusted Parse API host. Point base_url at "
+                    f"https://{_CANONICAL_HOST} (the default) or a loopback URL for local dev.",
+                )
+            raise AuthError(0, "No Parse credentials found. Set PARSE_API_KEY, run "
+                               "`parse login` / `parse login --web`, or pass api_key=.")
+        # Percent-encode both path segments (safe="") so a hostile SCRAPER_ID /
+        # endpoint_name cannot traverse the path (`../../admin`) or smuggle
+        # `?query` / `#fragment` — _request is public, so this holds for every
+        # caller, not just codegen-gated names. A legit id/endpoint
+        # ([A-Za-z0-9_-]) is untouched by quoting.
+        sid = urllib.parse.quote(self.SCRAPER_ID, safe="")
+        ep = urllib.parse.quote(endpoint_name, safe="")
+        url = f"{self._base_url}/scraper/{sid}/{ep}"
+        # X-API-Key when a key is present, else the web-login Bearer token (both
+        # host-gated above). api_key takes priority when both somehow exist.
+        headers = {"X-API-Key": key} if key else {"Authorization": f"Bearer {token}"}
+        # Attribution: lets the backend track SDK-originated usage (vs raw REST/MCP)
+        # and SDK version adoption. Purely informational — never gates the request.
+        headers["X-Parse-Client"] = _client_header()
+        # Version-pin a marketplace canonical: the executor reads this header and
+        # serves the pinned RELEASE snapshot (a positive int — the only shape it
+        # accepts). Only emitted for a pinned client (PINNED_VERSION set), so
+        # owned/account clients are byte-for-byte unchanged.
+        if self.PINNED_VERSION is not None:
+            headers["API-Snapshot-Version"] = str(self.PINNED_VERSION)
+        method_u = method.upper()
+        cleaned = {k: self._serialize_param(v) for k, v in params.items() if v is not None}
+        if method_u in ("GET", "HEAD", "DELETE"):
+            # dict/list params are JSON-encoded into the query string (executor
+            # contract; pinned by test_request_get_encodes_list_and_dict_as_json_query).
+            wire_params: Dict[str, Any] = {}
+            for k, v in cleaned.items():
+                if isinstance(v, (dict, list)):
+                    wire_params[k] = json.dumps(v)
+                elif isinstance(v, bool):
+                    wire_params[k] = str(v).lower()
+                else:
+                    wire_params[k] = v
+            req_kwargs: Dict[str, Any] = {"params": wire_params}
+        else:
+            req_kwargs = {"json": cleaned}
+        if timeout is not None:
+            req_kwargs["timeout"] = timeout
+
+        retryable = method_u in self._RETRY_SAFE_METHODS and self._max_retries > 0
+        started = _monotonic()
+        attempt = 0
+        while True:
+            try:
+                r = self._client.request(method_u, url, headers=headers, **req_kwargs)
+            except httpx.HTTPError as e:
+                # The billing claim is scoped by failure phase: a connect-phase
+                # error provably never reached the server; a read-phase error
+                # (timeout, dropped response) may have executed — and billed —
+                # the scrape, so an agent must not retry on a "not billed"
+                # promise the message can't keep.
+                billed = (
+                    "no request was billed"
+                    if isinstance(e, (httpx.ConnectError, httpx.ConnectTimeout))
+                    else "the request may have reached the server"
+                )
+                raise UpstreamError(
+                    0,
+                    f"network error calling {endpoint_name!r} at {self._base_url}: {e} "
+                    f"— check connectivity/base_url; {billed}.",
+                ) from e
+            body = _safe_json(r)
+            meta = RequestMeta.from_headers(r.headers)
+            if r.status_code < 400:
+                self.last_meta = meta
+                return unwrap_scraper_envelope(body)  # strip ScraperResult envelope
+            err = _build_error(r.status_code, body, fallback=f"{endpoint_name} failed",
+                               error_classes=getattr(self, "_ERROR_CLASSES", None),
+                               headers=r.headers, params=params)
+            err.meta = meta
+            # Only a 429 on a safe method is retried; everything else surfaces.
+            if not (retryable and r.status_code == 429 and attempt < self._max_retries):
+                raise err
+            attempt += 1
+            wait = self._retry_backoff(attempt, getattr(err, "retry_after", None))
+            # Total-elapsed cap on WALL CLOCK (request time included, not just
+            # sleeps): if this wait would blow the budget, surface the
+            # backpressure instead of sleeping past it. Read the class const
+            # via ``self.`` so a subclass override flows through.
+            if (_monotonic() - started) + wait > self._RETRY_TOTAL_BUDGET:
+                raise err
+            self._retry_sleep(wait)
+
+
+def unwrap_scraper_envelope(body: Any) -> Any:
+    """Strip the ScraperResult envelope: a ``{"status": "success", "data": ...}``
+    body returns ``data`` (so ``items_path`` / field access is relative to the
+    unwrapped body); anything else passes through. SINGLE source of this
+    predicate — the codegen sample-projection (``codegen_reconcile``) imports it
+    so build-time projection unwraps EXACTLY as serving-time runtime does."""
+    if isinstance(body, dict) and "data" in body and body.get("status") == "success":
+        return body["data"]
+    return body
+
+
+def _walk(d: Any, path: str, default: Any = None) -> Any:
+    """Resolve a DOTTED response path (``'a.b.c'``) against a nested dict,
+    returning ``default`` the moment a segment is absent or a non-dict is hit.
+
+    The runtime arm of the dotted-pagination-path fix: a paginated ``_fetch_page``
+    reads cursor / has-more / total-pages / page metadata (and a nested
+    ``items_path`` parent) off the page body, and a flat ``_resp.get('a.b')`` can
+    never reach a value nested under ``a`` — it silently truncated every
+    dotted-path spec to page 1. FLAT (dot-free) paths never reach here: codegen
+    emits a verbatim ``_resp.get(path)`` for those, so this helper is imported
+    ONLY by modules that actually declare a dotted pagination path (and existing
+    generated modules never reference it — a purely additive runtime symbol)."""
+    for seg in path.split("."):
+        if not isinstance(d, dict) or seg not in d:
+            return default
+        d = d[seg]
+    return d
+
+
+def _extract_items(resp: Any, items_path: str) -> List[Any]:
+    """Pull the declared ``items_path`` array out of one paginated page's
+    POST-unwrap response body (the caller has already run
+    ``unwrap_scraper_envelope``). The SAMPLE-INDEPENDENT half of the
+    empty-results discriminator — the emitted modules call it directly when the
+    op captured no sample, and it is the runtime safety net every
+    already-generated module inherits on the next import bump.
+
+    Disposition (each a strict safety improvement over the historical
+    ``if items_path not in _resp: raise`` that crashed any body lacking the
+    key):
+
+      * ``resp`` is a **list** — a top-level-list page: the value IS the items,
+        return it (the historical guard ``AttributeError``ed / crashed here).
+      * ``resp`` is ``None`` / empty / falsy (envelope-null, ``{}``) — a
+        legitimate zero-result page → ``[]`` (never raise).
+      * ``resp`` is a dict and ``items_path`` is **present + a list** — return
+        it (unchanged behavior).
+      * ``resp`` is a dict and ``items_path`` is **present but NOT a list**
+        (``{jobs: {...}}`` / ``{jobs: 5}``) — the spec's ``items_path`` points at
+        a non-array; today this is silent garbage / a downstream ``TypeError``,
+        so fail loud with an enriched :class:`PaginationError` (mis-derived;
+        sample-INDEPENDENT, unambiguous). This is the cross-compat-safe upgrade.
+      * ``resp`` is a dict and ``items_path`` is **absent** — return ``[]``. No
+        "list under another key → raise" heuristic lives here: an
+        already-generated / no-sample module cannot disambiguate a faceted
+        zero-result (``{results: [], facets: [...]}``) from a mis-derivation, so
+        the runtime arm fails SAFE. The mis-derivation raise lives ONLY in the
+        emitted discriminator, which has the captured sample to decide.
+    """
+    if isinstance(resp, list):
+        return resp
+    if not isinstance(resp, dict):
+        # envelope-null / None / a non-dict non-list scalar body → zero results.
+        return []
+    if items_path not in resp:
+        return []
+    value = resp.get(items_path)
+    if isinstance(value, list):
+        return value
+    if value is None:
+        # Key present but null — a zero-result page that declared the key. Treat
+        # as empty (the same disposition an absent key gets), never garbage.
+        return []
+    # Key present but a non-list, non-null value: the array the spec promised is
+    # not there. Sample-independent → fail loud (mis-derived items_path).
+    _list_keys = [k for k, v in resp.items() if isinstance(v, list)]
+    raise PaginationError(
+        0,
+        f"items_path {items_path!r} resolved to a {type(value).__name__}, not a "
+        f"list; list-bearing keys present={_list_keys}; spec likely mis-derived; "
+        f"regenerate",
+        body=resp,
+    )
+
+
+def _safe_json(r: httpx.Response) -> Any:
+    try:
+        return r.json()
+    except Exception:
+        return r.text