parse-sdk 0.1.0__py3-none-any.whl

parse_sdk/codegen_v2.py

@@ -0,0 +1,3361 @@
+"""Resource-modeled .py codegen.
+
+Input: an SDKSchema dict from the executor's ``/sdk/schemas`` endpoint
+(see services/executor/routers/sdk.py). When the schema has a
+``resources`` block (i.e. the agent modeled the domain), this codegen
+produces a real Python module:
+
+    parse_apis/<slug>/__init__.py
+
+Module contents:
+  * Resource classes per ``resources`` entry — fields, methods,
+    sub-resource collections.
+  * Enum classes per ``enums`` entry — real ``enum.Enum`` subclasses.
+  * Error classes per ``errors`` entry — subclasses of ``ParseError``.
+  * The root client class (e.g. ``Reddit``) with top-level collections.
+  * A registry ``_RESOURCE_CLASSES`` so the runtime ``Resource._from_payload``
+    can resolve nested resource types during coercion.
+
+The user imports `from parse_apis.<slug> import <RootClass>` — ``parse_apis``
+is a real project-local package on disk (written by ``parse sync``), so the
+import resolves with no import magic.
+
+Specs without a ``resources`` block are rejected — the SDK is hard-cutover
+to the resource-modeled world (per product decision). The raw HTTP path
+through the executor still works for those APIs.
+"""
+
+from __future__ import annotations
+
+import functools
+import json
+import keyword
+import logging
+import re
+from datetime import datetime, timezone
+from typing import Any, Dict, FrozenSet, List, Optional, Set, Tuple
+
+from parse_sdk import scaffold as _scaffold
+from parse_sdk._labels import split_top
+
+logger = logging.getLogger(__name__)
+
+
+# The runtime BASE error names every per-slug module re-exports, sourced from
+# ONE place (the committed scaffold's re-export set) filtered to the error
+# names — so it cannot drift from the runtime/scaffold vocabulary. ``RequestMeta``
+# is dropped (it's a value type, not an exception). These are pre-reserved in
+# ``_ModuleNames`` so a domain error whose spec-key camels to a base name
+# (``parse_error`` → ``ParseError``) deterministically suffixes, and are appended
+# to ``__all__`` so a generic ``from parse_apis.<slug> import ParseError`` works.
+_BASE_ERROR_EXPORTS: Tuple[str, ...] = tuple(
+    n for n in _scaffold._REEXPORTED if n != "RequestMeta"
+)
+
+
+# The per-module re-export of the runtime base errors is derived from the SAME
+# single source as ``__all__`` (``_BASE_ERROR_EXPORTS``), so a base error added
+# to ``scaffold._REEXPORTED`` lands in BOTH the import and ``__all__`` — never a
+# name exported-but-undefined.
+_HEADER_BASE_ERROR_IMPORTS = "".join(
+    f"    {n},\n" for n in _BASE_ERROR_EXPORTS
+)
+
+_HEADER = '''"""Auto-generated by `parse sync`. Do not edit by hand.
+
+Source: {base_url}
+API:    {api_name} ({slug})
+ID:     {scraper_id}
+Engine: parse_sdk {engine_version}
+Generated at: {timestamp}
+"""
+
+from __future__ import annotations
+
+import enum
+from datetime import datetime
+from decimal import Decimal
+from typing import Any, Dict, Iterator, List, Literal, Optional, ClassVar
+
+from parse_sdk._runtime import (
+''' + _HEADER_BASE_ERROR_IMPORTS + ''')
+# Runtime bases the GENERATED CODE subclasses-or-references by name are bound
+# under reserved private aliases so a DOMAIN resource named ``Collection`` /
+# ``Resource`` / ``Paginator`` / ``BaseAPI`` (or an error named ``ParseError``)
+# cannot shadow the base it must derive from. Domain names and runtime-base
+# names then live in disjoint namespaces — correct-by-construction. The bare
+# error subclasses above (incl. the public base ``ParseError``) stay importable
+# for user re-export; the generated code subclasses the ``_ParseError`` private
+# alias below, so the disjoint-namespace invariant is untouched.
+from parse_sdk._runtime import (
+    BaseAPI as _BaseAPI,
+    Collection as _Collection,
+    Paginator as _Paginator,
+    PaginationError as _PaginationError,
+    ParseError as _ParseError,
+    Resource as _Resource,
+)
+
+
+'''
+
+
+class CodegenError(Exception):
+    """A spec reached codegen in a state the gate should have rejected — a
+    collection op with no pagination block, or an unrecognized scheme. Codegen
+    REFUSES to guess the response shape (the legacy OR-chain is gone), so it
+    fails loud. ``parse sync`` catches this and skips+warns the API (the raw
+    HTTP endpoints still work); an in-process render surfaces it directly. This
+    is the SOLE presence-enforcer on the gate-less ``parse sync``/``row_to_spec``
+    path — not redundant defense-in-depth."""
+
+
+# A scraper id / endpoint name becomes a URL path segment of every runtime
+# request. The runtime sink percent-encodes both segments (the hard guarantee);
+# this gate is the EARLY authoring signal — a draft with a traversal-shaped id
+# or endpoint fails at render (``parse sync`` skips+warns; preview returns no
+# module) instead of generating a client that 404s at the user's runtime.
+# Verified against the real corpus: ids are UUIDs, endpoint charset is [a-z_],
+# so this rejects nothing legitimate.
+_WIRE_SEGMENT_RE = re.compile(r"[A-Za-z0-9_-]+")
+
+
+def _require_wire_segment(value: Any, what: str) -> None:
+    """Raise ``CodegenError`` unless ``value`` is a clean URL path segment."""
+    if not isinstance(value, str) or not _WIRE_SEGMENT_RE.fullmatch(value):
+        raise CodegenError(
+            f"{what} {value!r} is not a valid URL path segment "
+            f"(must match [A-Za-z0-9_-]+)"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Identifier / type-label helpers
+# ---------------------------------------------------------------------------
+
+
+_PY_KEYWORDS_AND_BUILTINS: Set[str] = set(keyword.kwlist) | {"None", "True", "False"}
+
+
+def _safe_ident(name: str, fallback: str = "x") -> str:
+    s = re.sub(r"[^0-9a-zA-Z_]", "_", name or "")
+    if not s:
+        return fallback
+    if s[0].isdigit():
+        s = f"_{s}"
+    if s in _PY_KEYWORDS_AND_BUILTINS:
+        s = f"{s}_"
+    return s
+
+
+def _docstring(text: str, indent: str = "    ") -> str:
+    """One safe docstring block (closing ``\"\"\"`` on its own line).
+
+    The block form is immune to a trailing/leading ``"`` or backslash in the
+    agent-inferred text (which the inline ``f'{indent}\"\"\"{text}\"\"\"'`` form
+    is NOT — a ``text`` ending in ``"`` produces an unterminated literal, failing
+    the WHOLE module's import). Every emitter routes its docstrings through this
+    helper rather than hand-building the literal. Returns the block WITHOUT a
+    trailing newline; callers join with ``\\n``.
+
+    A backslash is escaped (an odd trailing ``\\`` would escape the closing
+    quote's newline-adjacency); an embedded ``\"\"\"`` is escaped so it can't
+    close the block early.
+    """
+    safe = text.replace("\\", "\\\\").replace('"""', '\\"\\"\\"')
+    body = "\n".join(f"{indent}{ln}".rstrip() for ln in safe.split("\n"))
+    return f'{indent}"""\n{body}\n{indent}"""'
+
+
+def _escape_header_field(value: Any) -> str:
+    """Neutralize a server/agent-authored value before it is ``.format()``-ed
+    into the triple-quoted module ``_HEADER`` docstring.
+
+    SEC: the header is the one schema sink that does NOT route through
+    ``_docstring()``. Apply the same triple-quote/backslash escaping (so a
+    ``name`` / ``base_url`` / ``slug`` / ``scraper_id`` carrying a triple-quote
+    cannot break out of the docstring into top-level generated statements) and
+    collapse newlines so a value cannot reshape the header layout.
+    """
+    s = str(value).replace("\\", "\\\\").replace('"""', '\\"\\"\\"')
+    return s.replace("\r", " ").replace("\n", " ")
+
+
+def _camel(name: str) -> str:
+    parts = re.split(r"[^0-9a-zA-Z]+", name or "")
+    return "".join(p[:1].upper() + p[1:] for p in parts if p) or "X"
+
+
+def _as_dict(v: object) -> Dict[str, Any]:
+    """Self-narrow a spec value to a dict, or ``{}`` — the codegen idiom for a
+    field that *should* be an object but may be malformed/absent. Replaces the
+    inline ``x = x if isinstance(x, dict) else {}`` so pyright narrows at the
+    call site without a per-site ternary. (Parent-guards — ``spec.get(k) if
+    isinstance(spec, dict) else …`` — guard a *different* object and are left
+    inline; this is only for the self-narrow.)"""
+    return v if isinstance(v, dict) else {}
+
+
+def _as_str(v: object) -> Optional[str]:
+    """Self-narrow a spec value to a str, or ``None``. Replaces the inline
+    ``x = x if isinstance(x, str) else None``."""
+    return v if isinstance(v, str) else None
+
+
+def _snake(name: str) -> str:
+    """snake_case a (possibly Pascal/camelCase) identifier so word boundaries
+    survive into the plural accessor: ``BankAccount`` → ``bank_account``,
+    ``ItemSummary`` → ``item_summary``, ``Series`` → ``series``,
+    ``TimeSeries`` → ``time_series``.
+
+    Load-bearing for pluralization: ``_pluralize`` lowercases its input on its FIRST line,
+    so ``_pluralize("BankAccount")`` collapses to ``bankaccounts`` (no boundary)
+    — the multiword accessor was unreadable AND its plural mis-derived
+    (``Series`` jammed to ``serieses`` only AFTER a boundary-less collapse lost
+    the ``series`` ending). Routing the heuristic through ``_pluralize(_snake(…))``
+    restores the boundary so the closed plural rule sees the FINAL word.
+
+    Boundaries are inserted before each uppercase run start (camel humps) and
+    before a digit run; existing non-alnum separators are normalized to ``_``.
+    The result is lowercased and collapsed (no leading/trailing/double ``_``).
+    Pluralization (``_pluralize``) still owns the final-word transform; this only
+    re-introduces the boundaries an all-lowercase collapse destroyed.
+    """
+    s = name or ""
+    # acronym→word boundary: HTTPServer → HTTP_Server ; camel hump: aB → a_B
+    s = re.sub(r"(?<=[A-Z])(?=[A-Z][a-z])", "_", s)
+    s = re.sub(r"(?<=[a-z0-9])(?=[A-Z])", "_", s)
+    # letter↔digit boundary: account2 / 2fa stay grouped per run
+    s = re.sub(r"(?<=[A-Za-z])(?=[0-9])", "_", s)
+    s = re.sub(r"(?<=[0-9])(?=[A-Za-z])", "_", s)
+    s = re.sub(r"[^0-9A-Za-z]+", "_", s)
+    return re.sub(r"_+", "_", s).strip("_").lower()
+
+
+@functools.lru_cache(maxsize=1)
+def _runtime_reserved_member_names() -> Set[str]:
+    """Identifiers a generated resource member (field / param / op / accessor)
+    must NOT take, because they are structural to the runtime ``Resource`` and
+    its codegen-emitted machinery.
+
+    Cached: the result is constant per process (``dir(_Resource)`` is fixed at
+    import; tests only ever REPLACE existing attrs), and it was recomputed for
+    every rendered op. Callers treat the set as read-only.
+
+    Seeded from ``dir(_Resource)`` (every runtime attr/method/ClassVar) ∪ the
+    construction kwargs ``_api``/``_parent``/``_extra`` ∪ the ``_sub_`` accessor
+    stash prefix's bare form. A wire field named ``_api`` or a ``takes``-key
+    ``self`` passes straight through ``_safe_ident`` (neither is a keyword/
+    builtin) and crashes — ``Resource.__init__() got multiple values for
+    '_api'`` at construction, or ``def search(self, self: …)`` SyntaxError at
+    import. Reserving them forces a deterministic suffix instead.
+    """
+    from parse_sdk._runtime import Resource as _Resource
+
+    return set(dir(_Resource)) | {"self", "_api", "_parent", "_extra"}
+
+
+def _allocate_ident(
+    raw: str, taken: Set[str], *, fallback: str, reserved: Set[str]
+) -> str:
+    """Allocate ONE unique python identifier for ``raw`` against ``taken``.
+
+    Sanitizes via ``_safe_ident`` (single fallback so call-sites can't diverge),
+    then deterministically suffixes ``_`` until the result is neither in
+    ``reserved`` (runtime-structural names) nor ``taken`` (siblings already
+    allocated). Mutates + returns into ``taken``. Deterministic: same inputs in
+    the same order yield the same idents.
+    """
+    ident = _safe_ident(raw, fallback=fallback)
+    while ident in reserved or ident in taken:
+        ident = f"{ident}_"
+    taken.add(ident)
+    return ident
+
+
+def _allocate_field_idents(
+    field_names: List[str], *, reserved: Set[str]
+) -> Dict[str, str]:
+    """``{wire field name → unique py ident}`` for one resource, computed ONCE.
+
+    The single source the field-emit loop, the ``keyed_by`` membership test,
+    ``_KEY_FIELD``, ``_FIELD_ALIASES``, and the constructible factory key all
+    read from — so a sanitize-collision (``a-b`` + ``a.b`` → ``a_b``) or a
+    sanitize-to-empty name (the ``""``/all-symbol fallback-divergence case)
+    can't drop a field or spuriously fail the key check. Reserved runtime names
+    are suffixed away (a field ``_api`` becomes ``_api_``).
+    """
+    taken: Set[str] = set()
+    out: Dict[str, str] = {}
+    for fname in field_names:
+        out[fname] = _allocate_ident(fname, taken, fallback="field", reserved=reserved)
+    return out
+
+
+def _coerce_type_label(label: Optional[str]) -> str:
+    """Normalize an agent-written type label to what the runtime accepts.
+
+    Inputs: ``str``, ``int``, ``datetime``, ``url``, ``Decimal``, ``Post``,
+    ``List[Post]``, ``Optional[int]``, etc. Outputs: same shape, with
+    illegal forms degraded to ``Any``.
+    """
+    if not label:
+        return "Any"
+    s = str(label).strip()
+    # Normalize lowercase primitives (agent may write "string" / "integer")
+    primitives = {
+        "string": "str", "str": "str", "text": "str",
+        "integer": "int", "int": "int",
+        "number": "float", "float": "float", "double": "float",
+        "boolean": "bool", "bool": "bool",
+        "any": "Any", "object": "Any", "dict": "Any",
+        "array": "List[Any]", "list": "List[Any]",
+        "null": "None",
+    }
+    if s.lower() in primitives:
+        return primitives[s.lower()]
+    # List[X] / Optional[X]: normalize the single inner label so a composite
+    # with a non-canonical inner (e.g. ``List[integer]``) becomes ``List[int]``
+    # instead of degrading to ``Any`` at resolve time.
+    #
+    # ARITY IS PART OF THE GATE (audit 2026-06-11): a malformed-arity
+    # composite (``Dict[str]``, ``List[str, int]``, ``Optional[a, b]``) is a
+    # syntactically valid annotation that makes ``typing.get_type_hints``
+    # RAISE at first use — ``_field_hints`` swallows that into an EMPTY hint
+    # map, silently disabling coercion AND identity for EVERY field on the
+    # class; on the returns/param paths it NameError/TypeError-blinds the
+    # preview walker and pyright. This is the single normalization funnel for
+    # all three sinks (fields, returns, params), so the arity check lives
+    # here and degrades to ``Any`` — the documented malformed-label path.
+    # Frozen-corpus blast radius: 0 of 71,640 field / 9,538 returns / 17,726
+    # param labels (replay byte-identical); future-input verdicts only.
+    for prefix in ("List[", "Optional["):
+        if s.startswith(prefix) and s.endswith("]"):
+            inner = s[len(prefix):-1]
+            if len(split_top(inner)) != 1:
+                return "Any"
+            return f"{prefix}{_coerce_type_label(inner.strip())}]"
+    # Dict[K, V]: normalize both halves, splitting at the TOP-LEVEL comma so a
+    # nested composite (``Dict[str, List[integer]]``) still splits correctly.
+    # Exactly two halves — ``typing.Dict`` accepts nothing else.
+    if s.startswith("Dict[") and s.endswith("]"):
+        args = split_top(s[len("Dict["):-1])
+        if len(args) != 2:
+            return "Any"
+        return f"Dict[{_coerce_type_label(args[0])}, {_coerce_type_label(args[1])}]"
+    # datetime / Decimal / url / email — keep
+    if s in {"datetime", "Decimal", "url", "email"}:
+        return s
+    # Otherwise treat as a resource class name (e.g. "Post", "Site")
+    return s
+
+
+def _allocate_returns(label: str, owning_alloc: str, owning_camel: str) -> str:
+    """Resolve a method ``returns`` label to the owning resource's ALLOCATED
+    class name when the label names the owning resource — `<Resource>` or
+    `List[<Resource>]` / `Optional[<Resource>]`, the only return shapes the
+    codegen emits and the routing predicates recognize.
+
+    This is the SINGLE point where a return label becomes an allocated name; the
+    emitted annotation, the `_coerce` label, and the `_RESOURCE_CLASSES` key all
+    read the rewritten value, so they cannot diverge. Identity-based (compares the leaf to THE one
+    owning resource), so it is unambiguous even when the owning resource's
+    `_camel` collides with another's. A label naming a DIFFERENT resource passes
+    through unchanged: for a non-colliding target its `_camel` form already equals
+    that resource's allocated name (a valid registry key); a reference to a
+    `_camel`-colliding other resource is an irreducible spec ambiguity (one
+    written name, two classes) and is out of scope. Idempotent when re-applied
+    with the SAME ``owning_alloc`` (which ``render_module`` guarantees — it is
+    stable per resource): a suffixed leaf `_camel`-collapses back to
+    ``owning_camel`` and re-resolves to the same ``owning_alloc``.
+    """
+    s = str(label).strip()
+    for prefix in ("List[", "Optional["):
+        if s.startswith(prefix) and s.endswith("]"):
+            return f"{prefix}{_allocate_returns(s[len(prefix):-1], owning_alloc, owning_camel)}]"
+    return owning_alloc if _camel(s) == owning_camel else s
+
+
+def _is_collection_label(label: str) -> bool:
+    return label.startswith("List[") or label.startswith("Optional[List[")
+
+
+def _is_container_field_label(label: str) -> bool:
+    """A field type label whose VALUE is a container (List/Dict/Set/Tuple,
+    possibly Optional-wrapped). Such a field can never serve as an identity
+    key: ``Resource.__hash__`` does ``hash((name, value))`` and a container
+    value raises ``TypeError`` — and a container has no stable identity
+    semantics to begin with."""
+    s = str(label).strip()
+    while s.startswith("Optional[") and s.endswith("]"):
+        s = s[len("Optional["):-1].strip()
+    return s.startswith(("List[", "Dict[", "Set[", "Tuple["))
+
+
+def _collection_element(returns: str) -> str:
+    """The element type X of a collection label, unifying ``List[X]`` and
+    ``Optional[List[X]]`` to the same ``X``; a non-collection label is its own
+    element (unchanged)."""
+    if returns.startswith("List[") and returns.endswith("]"):
+        return returns[5:-1]
+    if returns.startswith("Optional[List[") and returns.endswith("]]"):
+        return returns[len("Optional[List["):-2]
+    return returns
+
+
+def _resp_path_expr(path: Any, default_expr: Optional[str] = None) -> str:
+    """Source expression resolving one pagination response path off ``_resp``.
+
+    A FLAT (dot-free) ``path`` keeps the verbatim ``_resp.get(...)`` — BYTE-
+    IDENTICAL to the historical emit, so a non-dotted spec's module is unchanged.
+    A DOTTED path dot-walks via the runtime ``_walk`` helper: a flat
+    ``_resp.get('pagination.next_cursor')`` can never reach a nested cursor and
+    silently truncated every dotted-path spec to page 1. ``default_expr`` is an
+    already-rendered source fragment (e.g. ``'_page'``) for the present-with-
+    default reads; ``None`` omits the default. A non-str ``path`` is treated as
+    flat (the repr passes through exactly as before — no behavior change)."""
+    if isinstance(path, str) and "." in path:
+        if default_expr is not None:
+            return f"_walk(_resp, {path!r}, {default_expr})"
+        return f"_walk(_resp, {path!r})"
+    if default_expr is not None:
+        return f"_resp.get({path!r}, {default_expr})"
+    return f"_resp.get({path!r})"
+
+
+def _emit_items(items_path: str, sample_keys: Optional[FrozenSet[str]]) -> List[str]:
+    """Emit the ``items_path`` extraction shared by every paginated arm — the
+    empty-results discriminator (emitted arm A + arm B).
+
+    ``_resp`` here is the RAW post-unwrap response value (the arms no longer
+    pre-coerce it to ``{}``), so it may be a dict, a top-level list, an
+    envelope-null ``None``, or empty. The single runtime helper
+    ``_extract_items`` owns the sample-INDEPENDENT normalization:
+
+      * top-level list → the value IS the items;
+      * envelope-null / ``None`` / empty / absent key → ``[]`` (legit zero);
+      * key present + list → the list; key present + non-list → fail loud
+        (``PaginationError``; mis-derived, sample-independent).
+
+    Arm B — the sample-PROVEN mis-derivation raise — is the ONLY home of the
+    sample-DEPENDENT verdict, and it is decided HERE at build time:
+
+      * ``sample_keys is None`` (no usable sample) → emit the bare
+        ``_extract_items`` call. Absent key → ``[]`` (never raise); a
+        present-but-non-list still fails loud (sample-independent).
+      * ``items_path`` **was** in the captured sample → the key is real; an
+        absent/empty response now is a legitimate zero-result → bare
+        ``_extract_items`` (same emit as no-sample).
+      * ``items_path`` was **NEVER** in a present sample → mis-derived. After
+        ``_extract_items`` (which fail-safes absent → ``[]``), raise the
+        enriched ``PaginationError`` when the live response is a POPULATED dict
+        that still omits the key — the populated-response-missing-the-key signal
+        that proves the array lives under a different key than the spec claims.
+        A genuinely-empty body (``{}`` / ``None`` / ``[]``) stays ``[]``: an
+        empty response is a zero-result, indistinguishable from a legit empty
+        page regardless of the sample, so it never heals-loud.
+    """
+    if isinstance(items_path, str) and "." in items_path:
+        # Dotted items_path ('envelope.items'): dot-walk to the leaf's PARENT,
+        # then hand the parent value + the leaf to _extract_items (which owns the
+        # absent / null / non-list / non-dict disposition — a missing segment
+        # makes _walk return None, which _extract_items maps to ``[]``). The
+        # sample-key discriminator keys on TOP-LEVEL response keys, so it cannot
+        # validate a nested leaf; skip the heal-loud arm — a dotted path is a
+        # structural spec assertion, not a sample-derived guess.
+        parent, leaf = items_path.rsplit(".", 1)
+        return [f"    items = _extract_items(_walk(_resp, {parent!r}), {leaf!r})"]
+    lines = [f"    items = _extract_items(_resp, {items_path!r})"]
+    if sample_keys is not None and items_path not in sample_keys:
+        # Sample present, key never in it → mis-derived. Heal loud only on a
+        # populated dict that omits the declared key (an empty body is a
+        # zero-result, not a mis-derivation signal).
+        lines += [
+            f"    if not items and isinstance(_resp, dict) and _resp and {items_path!r} not in _resp:",
+            f"        raise _PaginationError(0, f\"items_path {items_path!r} absent from a "
+            f"populated response; keys={{list(_resp)}}; the key was never in the captured "
+            f"sample — spec likely mis-derived; regenerate\", body=_resp)",
+        ]
+    return lines
+
+
+def _annotation_label(label: str) -> str:
+    """Convert a codegen type label into a Python annotation pyright understands.
+
+    Codegen uses ``url`` / ``email`` as semantic types — the runtime treats
+    them as ``str``, but pyright sees an undefined name. Recursively rewrite
+    any occurrence of those tokens (including inside ``List[url]`` etc.) to
+    ``str``. Everything else passes through.
+    """
+    s = label
+    # Wrap with word boundaries via regex so we don't munge identifiers that
+    # happen to contain "url".
+    s = re.sub(r"\burl\b", "str", s)
+    s = re.sub(r"\bemail\b", "str", s)
+    # ``Any`` is fine; ``object`` should map to ``Any`` for typing purposes
+    s = re.sub(r"\bobject\b", "Any", s)
+    return s
+
+
+# Type labels _coerce_type_label produces that are real, importable annotations
+# for a wire INPUT param. Anything else it returns is its "treat as a resource
+# class name" passthrough — never valid for an input param — so we degrade to Any.
+_KNOWN_PARAM_LABELS = frozenset({
+    "str", "int", "float", "bool", "bytes", "Any", "None",
+    "datetime", "Decimal", "url", "email",
+})
+
+# Leaf labels that are always resolvable in a generated module (built-ins +
+# the runtime-imported special types). ``url``/``email`` are launderable to
+# ``str`` by _annotation_label; ``object`` → ``Any``. Composite *wrappers*
+# (List/Optional/Dict) and a Literal[...] form are handled structurally.
+_KNOWN_FIELD_LEAF_LABELS = frozenset({
+    "str", "int", "float", "bool", "bytes", "Any", "None",
+    "datetime", "Decimal", "url", "email", "object",
+})
+
+# A leaf name (identifier or dotted) that could appear inside a field
+# annotation. Used to walk a composite's inner names so a dangling INNER ref
+# (``List[UnknownResource]``) is caught — get_type_hints evaluates the whole
+# annotation string, so every leaf must resolve.
+_LEAF_NAME_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
+
+
+def _referenced_resource_names(label: Optional[str], resource_names: Set[str]) -> Set[str]:
+    """Resource names a type label references, across composites (``List[X]`` /
+    ``Optional[X]`` / ``Dict[K, V]``).
+
+    The SINGLE source for "what resource types this label names" — used by the
+    field-resolvability gate AND the orphan/coverage check, so neither
+    re-implements composite parsing. The label is normalized through
+    ``_coerce_type_label`` first so a non-canonical inner (``List[integer]``)
+    can't masquerade as a resource leaf, then every identifier leaf is matched
+    and intersected with the emitted resource names.
+    """
+    if not label:
+        return set()
+    return {
+        m.group(0) for m in _LEAF_NAME_RE.finditer(_coerce_type_label(label))
+    } & resource_names
+
+
+def _field_annotation_resolvable(
+    label: str,
+    *,
+    resource_names: Set[str],
+    enum_names: Set[str],
+) -> bool:
+    """Whether every non-keyword leaf name in ``label`` resolves against
+    ``{known leaf labels} ∪ {emitted resource names} ∪ {emitted enum names}``.
+
+    The label is assumed to already be a syntactically-plausible annotation
+    (``_coerce_type_label`` output): a leaf label, or a ``List[...]`` /
+    ``Optional[...]`` / ``Dict[...]`` / ``Literal[...]`` composite. We extract
+    every identifier and require each to be a known leaf, an emitted
+    resource/enum, or a typing wrapper — so a dangling enum/resource ref
+    (bare OR nested inside a composite) fails the gate and degrades to ``Any``.
+
+    A Literal[...]'s string members are NOT identifiers we resolve against
+    names; but ``_annotation_label``/``_coerce_type_label`` never produce
+    Literal for a FIELD (only params), so a Literal leaf here is treated as
+    unresolvable (degrade to Any) — conservative and lenient.
+    """
+    # Resource-name leaves come from the single composite-extraction helper, so
+    # this gate and the orphan/coverage check agree on what a label references.
+    referenced = _referenced_resource_names(label, resource_names)
+    known = _KNOWN_FIELD_LEAF_LABELS | referenced | enum_names
+    # Typing wrappers that may legitimately appear in a composite.
+    wrappers = {"List", "Optional", "Dict", "Union"}
+    for m in _LEAF_NAME_RE.finditer(label):
+        name = m.group(0)
+        if name in wrappers:
+            continue
+        if name in known:
+            continue
+        return False
+    return True
+
+
+def _field_annotation(
+    coerced_label: str,
+    *,
+    resource_names: Set[str],
+    enum_names: Set[str],
+) -> str:
+    """The Python annotation to emit for a resource field, gated for
+    resolvability + injection.
+
+    ``coerced_label`` is ``_coerce_type_label`` output (or an enum-binding's
+    ``_camel(name)``). We:
+
+      1. Reject anything that isn't a leaf or a plain List/Optional/Dict/Literal
+         composite shape (an injection like ``List[evil')]`` fails the bracket
+         match → ``Any``).
+      2. Require every inner leaf name to resolve (dangling enum/resource ref,
+         incl. an unresolvable INNER name, → ``Any``).
+      3. Launder ``url``/``email``/``object`` via ``_annotation_label``.
+
+    Degrades to ``Any`` on any failure — B's ``get_type_hints`` resolution is
+    load-bearing, so an unresolvable annotation would NameError-poison the
+    class, and a hostile token would SyntaxError the module. Never raises.
+    """
+    label = coerced_label.strip()
+    if not label:
+        return "Any"
+    # Structural shape check: a bare identifier-ish leaf, or a balanced
+    # List[..]/Optional[..]/Dict[..]/Literal[..] composite. Anything with
+    # stray quotes / parens / unbalanced brackets is an injection attempt.
+    if not _is_well_formed_annotation(label):
+        return "Any"
+    if not _field_annotation_resolvable(
+        label, resource_names=resource_names, enum_names=enum_names
+    ):
+        return "Any"
+    return _annotation_label(label)
+
+
+def _is_well_formed_annotation(label: str) -> bool:
+    """A conservative structural check: the label is a leaf or a nested
+    composite built only from identifiers, the typing wrappers, brackets,
+    commas, and whitespace — OR a single top-level ``<X> | str`` union (the open
+    enum/leaf field form, C1/D2). Rejects quotes/parens/operators (injection),
+    unbalanced brackets, interior/multiple pipes, and a right arm other than
+    ``str``."""
+    # C1: admit exactly one top-level ``<X> | str`` union — validate the left arm
+    # as a plain leaf/composite and require the right arm to be exactly ``str``.
+    # ``partition`` splits on the FIRST pipe, so a second pipe (an interior pipe
+    # like ``List[A|B]`` or a third arm ``A | B | str``) lands in ``right`` and
+    # fails the ``str`` check → rejected. The left arm has no pipe, so the
+    # recursion terminates in the bracket/charset branch below.
+    if "|" in label:
+        left, _, right = label.partition("|")
+        if right.strip() != "str":
+            return False
+        return _is_well_formed_annotation(left.strip())
+    # Only allow identifier chars, brackets, commas, and whitespace. NO dots:
+    # codegen never emits a dotted annotation (every header import is a bare
+    # name), and a dotted label like ``datetime.datetime`` would pass the
+    # leaf-name check yet make ``get_type_hints`` raise ``AttributeError`` at
+    # first construction — poisoning EVERY field on the class. Reject it here so
+    # it degrades to ``Any`` (raw passthrough) instead.
+    if not re.fullmatch(r"[A-Za-z0-9_\[\],\s]*", label):
+        return False
+    # Balanced brackets.
+    depth = 0
+    for ch in label:
+        if ch == "[":
+            depth += 1
+        elif ch == "]":
+            depth -= 1
+            if depth < 0:
+                return False
+    # Whitespace is legal ONLY immediately after a comma (the ``, `` separator a
+    # ``Dict[K, V]`` composite emits). Any other interior space (``a b``) passes
+    # the charset/bracket checks yet is invalid in annotation position — it would
+    # SyntaxError at compile and (under ``from __future__ import annotations``)
+    # poison ``get_type_hints`` — so reject it and let the label degrade to
+    # ``Any``. The ``<X> | str`` union arm above returns BEFORE this guard (it
+    # recurses on the whitespace-free left arm), so open-enum unions are
+    # unaffected.
+    if any(ch.isspace() and (i == 0 or label[i - 1] != ",") for i, ch in enumerate(label)):
+        return False
+    return depth == 0
+
+
+def _param_annotation(
+    info: Any,
+    enum_alloc: Optional[Dict[str, str]] = None,
+    enums: Optional[Dict[str, Any]] = None,
+) -> str:
+    """Python annotation string for one endpoint input param.
+
+    ``info`` is the per-param ``ParamSpec`` dict from ``input_params`` (or
+    anything at all — this is the join's defensive boundary). Precedence:
+
+      1a. CLOSED enum-binding (``{"enum": "Sort", "closed": true}``) whose codes
+          resolve from ``enums`` → ``Sort | Literal['score', 'created_utc']``
+          (no ``| str`` — the value set is a contract, D2)
+      1b. open enum-binding (``{"enum": "Sort"}``) → ``Sort | str``
+      2. explicit closed ``choices`` (``["a", "b"]``) → ``Literal['a', 'b'] | str``
+      3. base ``type`` → ``_annotation_label(_coerce_type_label(type))``
+      4. anything unusable → ``Any``
+
+    Both the enum and ``choices`` forms are *open* (``| str``): they never
+    type-reject an unobserved-but-valid value, which is the right default for
+    an SDK whose value sets are agent-discovered. **Prose / ``description``
+    is never scraped** — only structured ``enum`` / ``choices`` are honored
+    (description inference is verified to mis-fire on real data).
+
+    ``enum_alloc`` maps ``_camel(enum-key) → allocated enum class name`` so an
+    enum-bound param references the real (possibly collision-suffixed)
+    class. When ``enum_alloc`` is supplied (the ``render_module`` path) the
+    binding resolves through it; without it (a standalone unit call) the binding
+    keeps its optimistic ``_camel(enum) | str`` form.
+
+    Always degrades to ``"Any"``; never raises. Handles ``info`` as a dict,
+    a dict missing ``type``, a bare string, or ``None``.
+    """
+    if not isinstance(info, dict):
+        return "Any"
+
+    # ``enum_alloc is not None`` discriminates the render_module path (the
+    # allocator dict is passed, possibly empty) from a standalone unit call
+    # (optimistic ``_camel(enum) | str`` form, pinned by tests) — capture it
+    # BEFORE the empty-dict normalization erases the distinction.
+    module_path = enum_alloc is not None
+    enum_alloc = enum_alloc or {}
+    enum_binding = info.get("enum")
+    if isinstance(enum_binding, str) and enum_binding.strip() and not (
+        # DANGLING binding on the module path (audit 2026-06-11): the enum is
+        # not emitted in this module, so ``<Undefined> | str`` would be a
+        # NameError that poisons get_type_hints over the method (silently
+        # fail-opening the preview walker on chains through it) and breaks
+        # pyright. Mirror the field path's resolvability degrade: fall
+        # through to the choices/type arms (an honest ``str``/``int``), the
+        # annotation the param would have carried without the binding.
+        # Frozen-corpus blast radius: 0 of 3,456 enum-bound params dangle.
+        module_path and _camel(enum_binding) not in enum_alloc
+    ):
+        # Resolve to the allocated class when the module allocator provided it
+        # (handles a collision suffix); else keep the canonical
+        # ``_camel`` spelling.
+        resolved = enum_alloc.get(_camel(enum_binding), _camel(enum_binding))
+        # A ``closed`` param is a contract: render ``Enum | Literal[codes]`` (no
+        # ``| str``) so an off-list value is a static type error — but ONLY when
+        # the codes actually resolve from ``enums`` (else stay open; ``| str``
+        # honestly admits an unobserved-but-valid value).
+        if info.get("closed") is True and isinstance(enums, dict):
+            codes = [c for _, c, _ in _enum_members(enums.get(enum_binding) or {},
+                                                    enum_name=resolved)]
+            if codes:
+                literal = "Literal[" + ", ".join(repr(c) for c in codes) + "]"
+                return f"{resolved} | {literal}"
+        return f"{resolved} | str"
+
+    choices = info.get("choices")
+    if (
+        isinstance(choices, list)
+        and choices
+        and all(isinstance(c, (str, int, float, bool)) for c in choices)
+    ):
+        return "Literal[" + ", ".join(repr(c) for c in choices) + "] | str"
+
+    type_label = info.get("type")
+    if not type_label:
+        return "Any"
+    coerced = _coerce_type_label(type_label)
+    # Only honor recognized primitive/special/composite labels. An unknown
+    # bare label is _coerce_type_label's resource-name passthrough — never
+    # valid for a wire input param, and would emit an undefined-name
+    # annotation — so degrade to Any.
+    if coerced in _KNOWN_PARAM_LABELS or (
+        coerced.startswith(("List[", "Optional[", "Dict["))
+        and _is_well_formed_annotation(coerced)
+    ):
+        return _annotation_label(coerced)
+    return "Any"
+
+
+def _params_for(
+    endpoint_input_params: Dict[str, Dict[str, Any]], op: Any
+) -> Dict[str, Any]:
+    """The ``input_params`` map for ``op``'s endpoint, or ``{}``.
+
+    Resolves the endpoint name defensively — a non-str / missing endpoint
+    yields an empty map so the op's kwargs degrade to ``Any`` rather than
+    keying the lookup with ``None``."""
+    endpoint = op.get("endpoint") if isinstance(op, dict) else None
+    if not isinstance(endpoint, str):
+        return {}
+    return endpoint_input_params.get(endpoint, {})
+
+
+def _method_for(endpoint_methods: Dict[str, str], op: Any) -> str:
+    """The HTTP method for ``op``'s endpoint, defaulting to ``POST``.
+
+    Mirrors ``_params_for``'s defensive endpoint resolution. A missing /
+    non-str endpoint or an endpoint not in the map → POST (matching the
+    executor projector and the raw client's defaults — never GET)."""
+    endpoint = op.get("endpoint") if isinstance(op, dict) else None
+    if not isinstance(endpoint, str):
+        return "POST"
+    return endpoint_methods.get(endpoint, "POST")
+
+
+def _desc_for(endpoint_descriptions: Dict[str, str], op: Any) -> Optional[str]:
+    """The endpoint ``description`` for ``op``'s endpoint, or ``None``.
+
+    Mirrors ``_method_for``'s defensive endpoint resolution — a missing /
+    non-str endpoint or one with no description yields ``None`` so the docstring
+    summary degrades to empty rather than fabricating one."""
+    endpoint = op.get("endpoint") if isinstance(op, dict) else None
+    if not isinstance(endpoint, str):
+        return None
+    return endpoint_descriptions.get(endpoint)
+
+
+def _sample_top_keys(return_schema: Any) -> Optional[FrozenSet[str]]:
+    """The ENVELOPE-UNWRAPPED top-level key-set of a captured ``return_schema``
+    sample, or ``None`` when the op captured no usable sample.
+
+    The empty-results discriminator (emitted arm B) needs to know which keys
+    the API's response actually carried so it can tell a legitimate zero-result
+    (the declared ``items_path`` WAS in the sample, just empty/absent this call)
+    from a mis-derivation (the key was NEVER there). Unwraps through the SAME
+    ``unwrap_scraper_envelope`` the build-time projection / serving-time runtime
+    use, so the key-set matches what ``_extract_items`` sees at run time — never
+    a ``{data, status}`` envelope assumption.
+
+    Returns ``None`` (no-sample) for: no ``return_schema``, no ``sample``, or a
+    sample that does not unwrap to a dict (a top-level-list / scalar sample
+    cannot prove a key absent vs present, so it is treated as undecidable → the
+    no-sample fail-safe path)."""
+    if not isinstance(return_schema, dict):
+        return None
+    sample = return_schema.get("sample")
+    if sample is None:
+        return None
+    from parse_sdk._runtime import unwrap_scraper_envelope
+
+    body = unwrap_scraper_envelope(sample)
+    if not isinstance(body, dict):
+        return None
+    return frozenset(body.keys())
+
+
+def _sample_keys_for(
+    endpoint_return_schemas: Dict[str, Any], op: Any
+) -> Optional[FrozenSet[str]]:
+    """The unwrapped sample top-level key-set for ``op``'s endpoint, or ``None``.
+
+    Parallel to ``_params_for`` — resolves the op's endpoint defensively (a
+    non-str / missing endpoint yields ``None``, the no-sample fail-safe) and
+    reads the captured ``return_schema`` for that endpoint through
+    ``_sample_top_keys``."""
+    endpoint = op.get("endpoint") if isinstance(op, dict) else None
+    if not isinstance(endpoint, str):
+        return None
+    return _sample_top_keys(endpoint_return_schemas.get(endpoint))
+
+
+def _sample_item_rows(return_schema: Any, items_path: Any) -> Optional[List[Any]]:
+    """The list of item rows under ``items_path`` in the ENVELOPE-UNWRAPPED
+    sample, or ``None`` when undecidable (no sample / no list under the key).
+
+    Mirrors the Step-0 census's ``_sample_item_rows`` EXACTLY (same unwrap, same
+    "list-or-None" rule) so the build-time eligibility decision reproduces the
+    documented 38-op population. ``None`` is the undecidable / no-dedup side."""
+    if not isinstance(return_schema, dict) or not isinstance(items_path, str):
+        return None
+    sample = return_schema.get("sample")
+    if sample is None:
+        return None
+    from parse_sdk._runtime import unwrap_scraper_envelope
+
+    body = unwrap_scraper_envelope(sample)
+    if not isinstance(body, dict):
+        return None
+    v = body.get(items_path)
+    return v if isinstance(v, list) else None
+
+
+def _dedup_eligible(return_schema: Any, items_path: Any, keyed_by: Optional[str]) -> bool:
+    """Whether the op is SAMPLE-PROVEN dedup-eligible: the element is
+    keyed AND the captured sample has >=2 item rows, EVERY one of which carries a
+    present (non-null) ``keyed_by`` value, AND those values are all distinct.
+
+    Tightened (F-4): the prior rule counted only the PRESENT keys and required
+    >=2 distinct, so it ignored rows with a missing/null ``keyed_by`` — a sample
+    like ``[{id:1},{title:x},{id:2}]`` read as "proven unique" off two keys while
+    a third row was unkeyed. That contradicts "sample-PROVEN-unique": a row whose
+    key the sample never showed is NOT proven uniquely identifiable, so emitting
+    dedup risks collapsing such rows by their id-hash fallback. Now require the
+    count of non-null keyed values to equal the TOTAL item-row count (every row
+    keyed — a non-dict row counts against the total and disqualifies) AND all
+    distinct. This is strictly MORE fail-safe (the plan's mandate).
+
+    Identity is compared by canonical JSON (``sort_keys``, ``default=str``) so
+    unhashable / non-primitive key values still compare. Keyless / no-sample /
+    <2-row / any-unkeyed-row / non-unique all return ``False`` (the fail-safe
+    NO-dedup disposition)."""
+    if not isinstance(keyed_by, str) or not keyed_by:
+        return False
+    rows = _sample_item_rows(return_schema, items_path)
+    if rows is None or len(rows) < 2:
+        return False
+    vals = [r.get(keyed_by) for r in rows if isinstance(r, dict)]
+    present = [v for v in vals if v is not None]
+    distinct = {json.dumps(v, sort_keys=True, default=str) for v in present}
+    # EVERY row must be keyed (present == total rows) AND keys all distinct. A
+    # non-dict row never contributes to ``present``, so it fails this equality.
+    return len(present) == len(rows) and len(distinct) == len(present)
+
+
+def _dedup_eligible_for(
+    endpoint_return_schemas: Dict[str, Any],
+    op: Any,
+    pg: Optional[Dict[str, Any]],
+    element_keyed_by: Dict[str, Optional[str]],
+    elem: str,
+) -> bool:
+    """Resolve the dedup-eligibility for ``op`` at its call site (parallel to
+    ``_sample_keys_for``). Defensive endpoint resolution; reads the element's
+    ``keyed_by`` from the threaded ``{allocated_element: keyed_by}`` map (the
+    element resource's key is NOT in the collection emitter's scope, so it must
+    be supplied via this map — round-2 fix)."""
+    endpoint = op.get("endpoint") if isinstance(op, dict) else None
+    if not isinstance(endpoint, str) or not isinstance(pg, dict):
+        return False
+    items_path = pg.get("items_path")
+    keyed_by = element_keyed_by.get(elem)
+    return _dedup_eligible(endpoint_return_schemas.get(endpoint), items_path, keyed_by)
+
+
+def error_class_names(schema: Dict[str, Any]) -> Dict[str, str]:
+    """``{error spec key → ALLOCATED class name}`` — what docgen's README
+    "Errors" section renders so it names the importable class even when the
+    module allocator suffixed a collision. Same normalize-then-allocate path
+    as ``render_module``/``op_call_descriptors`` (a standalone READ; no
+    emitted-source path is touched)."""
+    return dict(_ModuleNames(_normalize_schema(schema)).errors)
+
+
+def endpoint_description_map(schema: Dict[str, Any]) -> Dict[str, str]:
+    """``{endpoint_name: description}`` — the single join rule for an
+    operation's narrative.
+
+    An operation's narrative is the ``description`` of the endpoint it calls.
+    Keyed on ``endpoints[].name`` (the shape both consumers pass: codegen
+    builds this after ``_normalize_schema`` folds raw ``endpoint_name`` → ``name``;
+    docgen reads the served ``SDKSchema`` whose endpoints already carry ``name``).
+    Both the docstring renderer (codegen) and the README "Description" column
+    (docgen) resolve this map by ``op["endpoint"]``. Only endpoints carrying a
+    non-empty ``description`` appear, so a missing/blank description degrades to
+    no narrative rather than an empty cell keyed on ``None``."""
+    out: Dict[str, str] = {}
+    for ep in schema.get("endpoints", []) or []:
+        if not isinstance(ep, dict):
+            continue
+        name = ep.get("name")
+        desc = ep.get("description")
+        if isinstance(name, str) and isinstance(desc, str) and desc.strip():
+            out[name] = desc.strip()
+    return out
+
+
+def _param_decl(ident: str, anno: str, required: bool) -> str:
+    """Render one signature parameter declaration.
+
+    Required → ``ident: anno`` (no default, so pyright flags omission).
+    Optional → ``ident: Optional[anno] = None`` (bare ``ident: Any = None``
+    when ``anno`` is ``Any`` — ``Optional[Any]`` is redundant noise).
+    """
+    if required:
+        return f"{ident}: {anno}"
+    if anno == "Any":
+        return f"{ident}: Any = None"
+    return f"{ident}: Optional[{anno}] = None"
+
+
+def _extract_field_spec(value: Any) -> Tuple[str, Optional[str], Optional[str]]:
+    """Pull (type_label, enum_binding, alias_from) out of a field declaration.
+
+    Backward-compatible: a bare string is treated as ``{type: <string>}``.
+    The dict form supports:
+      * ``{"type": "str", "enum": "Condition"}``      — field is typed Condition
+      * ``{"type": "datetime", "alias_from": "created_utc"}`` — wire-name override
+    """
+    if isinstance(value, str):
+        return value, None, None
+    if isinstance(value, dict):
+        type_label = value.get("type") or "Any"
+        enum_binding = value.get("enum")
+        enum_binding = _as_str(enum_binding)
+        alias_from = value.get("alias_from")
+        alias_from = _as_str(alias_from)
+        return type_label, enum_binding, alias_from
+    return "Any", None, None
+
+
+def _field_description(value: Any) -> Optional[str]:
+    """The optional per-field ``description`` (dict-form FieldSpec only).
+
+    A bare-string field (``"int"``) has none. The dict form may carry a
+    ``description`` alongside ``type``/``enum``/``alias_from``; codegen
+    otherwise ignores it, so this is its one read. Returns a stripped
+    non-empty string or ``None``.
+    """
+    if isinstance(value, dict):
+        d = value.get("description")
+        if isinstance(d, str) and d.strip():
+            return d.strip()
+    return None
+
+
+def _op_has_self_pin(op: Dict[str, Any]) -> bool:
+    """Whether ``op`` has any pin that references ``$self`` — i.e. a value that
+    can only be resolved from a live resource INSTANCE (``$self.name`` →
+    ``self._parent.name`` on a collection). Such an op cannot be emitted on a
+    resource's ROOT collection (``_parent`` is always None there → it would
+    crash with ``AttributeError`` at call time); it lives only on the
+    resource-nav path (``reddit.subreddit("x").search_posts(...)``).
+
+    This is the SINGLE routing invariant: an op is an instance method IFF it has
+    a ``$self`` pin, and a root-collection method IFF it does NOT — the two emit
+    sets are exact complements. A pinless op has no way to reference the instance
+    (``$self`` is the spec's only instance-reference mechanism), so it is a
+    lookup/factory that belongs on the collection by construction."""
+    pins = op.get("pins")
+    pins = _as_dict(pins)
+    return any(isinstance(v, str) and v.startswith("$self") for v in pins.values())
+
+
+def _schema_has_paginated_op(resources: Dict[str, Any]) -> bool:
+    """Whether ANY op in the (normalized) resources — top-level or sub-resource —
+    declares a pagination scheme. Gates the emitted ``_extract_items`` import:
+    the extraction helper is referenced ONLY inside a paginated ``_fetch_page`` body, so
+    a non-paginated-only module must stay byte-identical (no unused import). One
+    walk over the same resource/sub-resource/operations shape ``render_module``
+    iterates."""
+    def _ops_paginated(ops: Any) -> bool:
+        if not isinstance(ops, dict):
+            return False
+        for opb in ops.values():
+            if not isinstance(opb, dict):
+                continue
+            pg = opb.get("pagination")
+            if isinstance(pg, dict) and pg.get("scheme"):
+                return True
+        return False
+
+    for rspec in resources.values():
+        if not isinstance(rspec, dict):
+            continue
+        if _ops_paginated(rspec.get("operations")):
+            return True
+        for sub in (rspec.get("sub_resources") or {}).values():
+            if isinstance(sub, dict) and _ops_paginated(sub.get("operations")):
+                return True
+    return False
+
+
+# Response-path fields the emitted ``_fetch_page`` resolves off ``_resp`` via the
+# dotted-aware helpers, keyed by scheme. ``items_path`` is read by EVERY scheme's
+# ``_emit_items``; the cursor / page metadata fields only by their own scheme.
+# This map is the SINGLE source the dotted-import gate and the per-op emit sites
+# both key on, so the emitted ``_walk`` import and its use can never diverge.
+_DOTTED_RESP_PATH_FIELDS_BY_SCHEME = {
+    "single_page": ("items_path",),
+    "time_cursor": ("items_path",),
+    "cursor": ("items_path", "next_cursor_path", "has_more_path"),
+    "page": ("items_path", "page_path", "total_pages_path"),
+}
+
+
+def _schema_has_dotted_pagination_path(resources: Dict[str, Any]) -> bool:
+    """Whether ANY paginated op declares a DOTTED (``'a.b'``) value in a response-
+    path field its scheme actually reads off ``_resp``. Gates the emitted
+    ``_walk`` import EXACTLY: the dot-walk helper is referenced only at a dotted
+    emit site, so a flat-path-only module stays byte-identical (no unused import,
+    no behavior change). The frozen corpus has ZERO dotted paths, so this import
+    is absent corpus-wide. Mirrors ``_schema_has_paginated_op``'s walk over the
+    resource/sub-resource/operations shape."""
+    def _is_dotted(v: Any) -> bool:
+        return isinstance(v, str) and "." in v
+
+    def _ops_have_dotted(ops: Any) -> bool:
+        if not isinstance(ops, dict):
+            return False
+        for opb in ops.values():
+            if not isinstance(opb, dict):
+                continue
+            pg = opb.get("pagination")
+            if not isinstance(pg, dict):
+                continue
+            scheme = pg.get("scheme")
+            if not isinstance(scheme, str):
+                continue
+            fields = _DOTTED_RESP_PATH_FIELDS_BY_SCHEME.get(scheme)
+            if fields and any(_is_dotted(pg.get(f)) for f in fields):
+                return True
+        return False
+
+    for rspec in resources.values():
+        if not isinstance(rspec, dict):
+            continue
+        if _ops_have_dotted(rspec.get("operations")):
+            return True
+        for sub in (rspec.get("sub_resources") or {}).values():
+            if isinstance(sub, dict) and _ops_have_dotted(sub.get("operations")):
+                return True
+    return False
+
+
+def _root_collection_emit_ops(operations: Any) -> List[str]:
+    """The op names that render as ROOT-collection methods: PINLESS ops (a
+    ``$self`` pin crashes on the root collection — ``_parent`` is None there) with
+    a resolvable string ``endpoint`` (``_render_operation_method`` emits NOTHING
+    for an endpoint-less op).
+
+    This is the SINGLE source the renderer, the docgen call-path, AND the
+    collection-emit gate all derive from, so the gate and the renderer can't
+    drift (a one-sided change would ``KeyError`` on the direct-indexed
+    ``names.root_collections[res_name]``). It is a NECESSARY condition for a
+    rendered method, not a sufficient one: an op that passes here can still fail
+    to render — e.g. a ``List[X]`` return with no ``pagination`` block makes
+    ``_render_operation_method`` raise ``CodegenError`` (fail-closed: the build
+    aborts loudly rather than shipping a silent dead collection). The synthesized
+    ``fetched_by`` ``.get`` is included automatically (``_normalize_schema``
+    injects it as a pinless, endpoint'd op before this runs).
+    """
+    if not isinstance(operations, dict):
+        return []
+    return [
+        n for n, b in operations.items()
+        if isinstance(b, dict) and not _op_has_self_pin(b) and isinstance(b.get("endpoint"), str)
+    ]
+
+
+def _constructible_unsafe_pin(spec: Dict[str, Any], keyed_by: str) -> Optional[str]:
+    """Why a flagged-``constructible`` resource is NOT safe to hand-build, or
+    ``None`` if it is safe.
+
+    A hand-built instance (``Resource(key=...)``) has ONLY ``keyed_by`` populated
+    — every other field is ``None``. So any op reachable from it that pins a
+    NON-key field of the instance silently sends ``None``. The resource is safely
+    constructible iff every ``$self``-derived pin — in its OWN ops AND in its
+    sub-resources' ops — references only ``keyed_by``.
+
+    Pin resolution mirrors ``_resolve_param_value`` + the collection remap
+    (see codegen below): in a SUB-resource (collection) op, codegen rewrites BOTH
+    ``$self.<f>`` and ``$self.parent.<f>`` onto the owning resource
+    (``self._parent.<f>``) — so in a sub-resource op a bare ``$self.<f>``
+    references the PARENT's field, identical to ``$self.parent.<f>``. Bare
+    ``$self`` / ``$self.parent`` reference the key itself (safe).
+
+    Returns the first offending ``"resource_field"`` (for an observability
+    warning), else ``None``.
+    """
+
+    def _instance_field(value: Any, *, sub: bool) -> Optional[str]:
+        """The owning-resource field a ``$self`` pin reads, or ``None`` when it
+        reads the key (safe) or isn't a ``$self`` pin (irrelevant)."""
+        if not isinstance(value, str):
+            return None
+        s = value.strip()
+        if not s.startswith("$self"):
+            return None
+        if sub:
+            # Every $self pin in a sub-resource op targets the PARENT.
+            if s in ("$self", "$self.parent"):
+                return None  # the parent's key — safe
+            if s.startswith("$self.parent."):
+                return s[len("$self.parent."):]
+            return s[len("$self."):]  # bare `$self.<f>` == `$self.parent.<f>` here
+        # Own op: bare `$self` is the key (safe); `$self.<f>` reads field f.
+        if s == "$self":
+            return None
+        return s[len("$self."):]
+
+    def _first_unsafe(ops: Any, *, sub: bool) -> Optional[str]:
+        if not isinstance(ops, dict):
+            return None
+        for op in ops.values():
+            if not isinstance(op, dict):
+                continue
+            pins = op.get("pins")
+            if not isinstance(pins, dict):
+                continue
+            for v in pins.values():
+                f = _instance_field(v, sub=sub)
+                if f is not None and f != keyed_by:
+                    return f
+        return None
+
+    offending = _first_unsafe(spec.get("operations"), sub=False)
+    if offending is not None:
+        return offending
+    # Sub-resources are scanned ONE level deep — matching codegen, which renders
+    # only one level of sub-resource ops. A doubly-nested sub-op is never emitted,
+    # so it's unreachable from a hand-built instance and can't send None; if the
+    # renderer ever recurses, this scan must recurse in lockstep.
+    sub_resources = spec.get("sub_resources")
+    if isinstance(sub_resources, dict):
+        for sub_spec in sub_resources.values():
+            if isinstance(sub_spec, dict):
+                offending = _first_unsafe(sub_spec.get("operations"), sub=True)
+                if offending is not None:
+                    return offending
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Module-level class-name allocator (P0.2)
+# ---------------------------------------------------------------------------
+
+
+class _ModuleNames:
+    """One module namespace shared by the root client, resource classes, enum
+    classes, error classes, and every sub-resource / root **collection** class.
+
+    Each emitter historically assumed its namespace was private, but they all
+    land in one module ``__init__.py`` and one ``__all__``. Two resources that
+    ``_camel``-collapse to one name (``Post`` + ``post``), an enum named the same
+    as a resource, an error == a resource, an enum == an error, ``root_name`` ==
+    a resource, or two sub-resources colliding — each silently dropped a class
+    or duplicated ``__all__`` on HEAD. The remedy is correct-by-construction:
+    allocate every module-level class name ONCE here, deterministic suffix on
+    ANY cross-kind collision, and thread the allocated name everywhere it's
+    referenced (class def, ``_RESOURCE_CLASSES`` keys, enum-binding rewrite,
+    accessors, collection class names, AND the resolvability gate's
+    ``emitted_resource_names``/``emitted_enum_names``).
+
+    Reservation order is fixed (resources → enums → errors → collections →
+    root) so the result is deterministic. Resources are reserved first because
+    they're the most cross-referenced (enum bindings, ``returns`` labels,
+    ``_RESOURCE_CLASSES`` keys all key on the resource's allocated name).
+    """
+
+    def __init__(self, schema: Dict[str, Any]) -> None:
+        self._taken: Set[str] = set()
+        # wire/spec key → allocated class name, per kind.
+        self.resources: Dict[str, str] = {}
+        self.enums: Dict[str, str] = {}
+        self.errors: Dict[str, str] = {}
+        # base-error name → allocated name (always the verbatim base name —
+        # they're reserved FIRST, so no suffix unless a later base would dup,
+        # which can't happen as the source tuple is unique).
+        self.base_errors: Dict[str, str] = {}
+        # (parent_spec_key, sub_spec_key) → collection class name.
+        self.sub_collections: Dict[Tuple[str, str], str] = {}
+        # resource spec key → root collection class name.
+        self.root_collections: Dict[str, str] = {}
+        # resource spec key → root collection ACCESSOR attr (the ``@property``
+        # name on the root client, e.g. ``boxes``). Allocated in its OWN
+        # namespace (root-client instance attrs, NOT the module class namespace)
+        # so two resources whose plurals collide (``box``→``boxes`` and
+        # ``boxe``→``boxes``) deterministically suffix instead of both emitting
+        # ``@property def boxes`` (Python keeps the last → one AttributeErrors).
+        self.root_collection_attrs: Dict[str, str] = {}
+        self._root_attr_taken: Set[str] = set()
+
+        # Pre-reserve the runtime BASE-error names FIRST (before resources /
+        # enums / errors). This ordering is load-bearing: it makes a domain
+        # error whose spec-key camels to a base name (``parse_error`` →
+        # ``ParseError``) deterministically suffix to ``ParseError_`` via the
+        # same allocator, while the bare base name stays bound to the runtime
+        # class. Threaded into ``__all__`` by ``all_exports()``.
+        for be in _BASE_ERROR_EXPORTS:
+            self.base_errors[be] = self._alloc(be)
+
+        resources = schema.get("resources")
+        resources = _as_dict(resources)
+        enums = schema.get("enums")
+        enums = _as_dict(enums)
+        errors = schema.get("errors")
+        errors = _as_dict(errors)
+
+        for rk, rv in resources.items():
+            if isinstance(rv, dict):
+                self.resources[rk] = self._alloc(_camel(rk))
+        for ek, ev in enums.items():
+            if isinstance(ev, dict):
+                self.enums[ek] = self._alloc(_camel(ek))
+        for erk, erv in errors.items():
+            if isinstance(erv, dict):
+                self.errors[erk] = self._alloc(_camel(erk))
+
+        # Sub-resource + root collection class names share the SAME namespace —
+        # derived from the resource's ALLOCATED name (not a fresh _camel) so a
+        # suffixed resource's collections stay consistent with it.
+        for rk, rv in resources.items():
+            if not isinstance(rv, dict):
+                continue
+            res_cls = self.resources[rk]
+            subs = rv.get("sub_resources")
+            subs = _as_dict(subs)
+            for sk, sv in subs.items():
+                if isinstance(sv, dict):
+                    self.sub_collections[(rk, sk)] = self._alloc(
+                        f"{res_cls}{_camel(sk)}Collection"
+                    )
+
+        # Root name reserved AFTER resources so a ``root_name`` colliding with a
+        # resource name is the one suffixed (the resource keeps the clean name,
+        # since it's the more cross-referenced symbol).
+        slug = schema.get("slug") or ""
+        root_raw = schema.get("root_name") or _camel(slug)
+        if not isinstance(root_raw, str) or not root_raw.isidentifier():
+            root_raw = _camel(slug)
+        self.root = self._alloc(root_raw)
+
+        # Root collection class names — only for resources WITH operations (the
+        # only ones that get a root collection). Reserved last so a collection
+        # name colliding with anything prior is suffixed.
+        #
+        # The emit gate DERIVES from the shared, named predicate
+        # ``resource_surface.resource_surface_facts`` (the SAME function docgen's
+        # ``_reachability_warnings`` and external consumers read), via
+        # the ``emits_client_accessor`` fact. Only resources whose root collection
+        # would have ≥1 real method get a collection (name + class + @property): an
+        # instance-only resource (all ops $self-pinned) or one whose only pinless
+        # op renders nothing would ship a dead ``client.<plural>`` accessor —
+        # suppressed by construction. The fact == ``has_root_collection`` ==
+        # ``bool(_root_collection_emit_ops(...))``, so this is behaviour-preserving
+        # — it removes the parallel computation, not the suppression.
+        from parse_sdk.resource_surface import resource_surface_facts
+        _facts = resource_surface_facts(schema)
+        for rk, rv in resources.items():
+            if not isinstance(rv, dict):
+                continue
+            rfacts = _facts.get(rk)
+            if rfacts is None or not rfacts.emits_client_accessor:
+                continue
+            res_cls = self.resources[rk]
+            plural = _plural_attr(res_cls, rv)
+            self.root_collections[rk] = self._alloc(f"{self.root}{_camel(plural)}Collection")
+            self.root_collection_attrs[rk] = self._alloc_root_attr(plural)
+
+    def _alloc_root_attr(self, name: str) -> str:
+        """Allocate a root-client accessor attr in its OWN namespace (distinct
+        from the module class namespace ``_taken``). Deterministic suffix on a
+        colliding plural so two resources never emit duplicate ``@property``s."""
+        ident = name
+        while ident in self._root_attr_taken:
+            ident = f"{ident}_"
+        self._root_attr_taken.add(ident)
+        return ident
+
+    def _alloc(self, name: str) -> str:
+        # Suffix ONLY the value-keywords (None/True/False), which ARE valid
+        # identifiers and so slipped past the old `name.isidentifier()` short-
+        # circuit and emitted `class None(...)` -> SyntaxError. Every other name
+        # (clean ASCII, Unicode identifiers like `Café`) is preserved verbatim —
+        # routing them through _safe_ident's ASCII-only regex would needlessly
+        # mangle valid class names. _safe_ident appends `_` to keywords.
+        if name.isidentifier() and name not in _PY_KEYWORDS_AND_BUILTINS:
+            ident = name
+        else:
+            ident = _safe_ident(name, fallback="X")
+        while ident in self._taken:
+            ident = f"{ident}_"
+        self._taken.add(ident)
+        return ident
+
+    def resource_values(self) -> Set[str]:
+        return set(self.resources.values())
+
+    def enum_values(self) -> Set[str]:
+        return set(self.enums.values())
+
+    def all_exports(self) -> List[str]:
+        """``__all__`` content: root + resources + enums + domain-errors + the
+        re-exported runtime base errors, dup-free by construction (the allocator
+        guarantees uniqueness across kinds; base errors were pre-reserved so
+        their verbatim names are present and any colliding domain error is
+        suffixed)."""
+        out = [self.root]
+        out.extend(self.resources.values())
+        out.extend(self.enums.values())
+        out.extend(self.errors.values())
+        out.extend(self.base_errors.values())
+        return out
+
+
+# ---------------------------------------------------------------------------
+# Spec walker — turns the SDKSchema dict into rendered .py source
+# ---------------------------------------------------------------------------
+
+
+def _safe_self_tail(tail: str, *, op: str = "") -> str:
+    """Validate a ``$self`` / ``$self.parent`` pin tail as a dotted chain of
+    Python identifiers, returning it verbatim.
+
+    A pin value is agent-inferred (non-authoritative) and the ``$self`` tail is
+    interpolated into generated SOURCE — ``_params['x'] = self.<tail>`` — so a
+    tail that is NOT a dotted-identifier path is an injection attempt, not a
+    renderable spec (``request_flow`` is JSONB, so a stored ``\\n`` is a real
+    newline at render time, turning ``id\\n  <stmt>`` into a body statement).
+    Every sibling value path is already neutralized (``$arg`` via ``_safe_ident``,
+    literals via ``repr``); this closes the ``$self`` hole.
+
+    Fail-closed (``CodegenError``) on a hostile tail — matching codegen's
+    contract for a spec the gate should have rejected (``parse sync`` skip+warns
+    that one API; the preview surfaces it). Empty tail is allowed (a bare
+    ``$self`` / ``$self.parent`` reference — the base object itself)."""
+    t = tail.strip()
+    if t == "":
+        return t
+    # Each segment must be an identifier AND not a Python keyword: ``isidentifier()``
+    # is True for keywords (``"class".isidentifier()`` → True), but ``self.class``
+    # is a SyntaxError that fails the whole module import — reject it here.
+    if not all(seg.isidentifier() and not keyword.iskeyword(seg) for seg in t.split(".")):
+        where = f" in op {op!r}" if op else ""
+        raise CodegenError(
+            f"pin value $self tail {tail!r}{where} is not a dotted-identifier path "
+            f"(gate should reject; refusing to interpolate into source)"
+        )
+    return t
+
+
+def _resolve_param_value(
+    expr: Any,
+    *,
+    self_var: str = "self",
+    op: str = "",
+) -> str:
+    """Turn a pin/takes value-spec into a Python expression string.
+
+    ``$self``         -> ``self`` (the resource itself; serialized to its key)
+    ``$self.field``   -> ``self.field``
+    ``$arg.name``     -> ``name`` (the method's local arg)
+    ``$self.parent``       -> ``self._parent`` (the owning resource itself)
+    ``$self.parent.field`` -> ``self._parent.field`` (one-level walk)
+    Anything else     -> repr() of the literal (str/int/bool/...).
+
+    ``$self`` tails are validated as dotted-identifier paths (``_safe_self_tail``)
+    so a hostile pin can't inject statements into the emitted method body.
+    """
+    if not isinstance(expr, str):
+        return repr(expr)
+    s = expr.strip()
+    # Bare forms (no trailing dot): handle BEFORE the dotted-prefix checks so they
+    # don't fall through to the repr() literal (``$self`` → ``'$self'``) or to the
+    # wrong ``$self.`` arm (``$self.parent`` → ``self.parent`` instead of
+    # ``self._parent``). Must agree with ``_op_has_self_pin`` (startswith "$self"),
+    # which routes such pins as instance methods.
+    if s == "$self":
+        return self_var
+    if s == "$self.parent":
+        return f"{self_var}._parent"
+    if s.startswith("$self.parent."):
+        tail = _safe_self_tail(s[len("$self.parent."):], op=op)
+        return f"{self_var}._parent.{tail}" if tail else f"{self_var}._parent"
+    if s.startswith("$self."):
+        tail = _safe_self_tail(s[len("$self."):], op=op)
+        return f"{self_var}.{tail}" if tail else self_var
+    if s.startswith("$arg."):
+        return _safe_ident(s[len("$arg."):])
+    # Literal
+    return repr(s)
+
+
+def _enum_members(
+    spec: Dict[str, Any], *, enum_name: str = ""
+) -> List[Tuple[str, str, Optional[str]]]:
+    """Ordered ``(IDENT, wire_code, display)`` for an enum spec — the single
+    source of an enum's member identity, shared by ``_render_enum`` (the class
+    body) and ``_param_annotation`` (a ``closed`` param's ``Literal[...]``).
+
+    IDENT is ``_safe_ident(variant).upper()``, deterministically suffixed on a
+    collision (two variants collapsing to one ident would ``TypeError`` at
+    import). ``wire_code`` is the declared ``code`` (or ``IDENT.lower()`` when
+    absent); an exact collision fails closed with ``CodegenError`` (a synthesized
+    suffix would be a dead member matching no wire value) — so a ``closed``
+    param's ``Literal`` lists exactly the values the generated enum carries.
+    """
+    values = spec.get("values") if isinstance(spec, dict) else None
+    if not isinstance(values, dict) or not values:
+        return []
+    out: List[Tuple[str, str, Optional[str]]] = []
+    seen_idents: Set[str] = set()
+    seen_codes: Set[str] = set()
+    for variant, body in values.items():
+        ident = _safe_ident(variant, fallback="VALUE").upper()
+        base_ident = ident
+        n = 2
+        while ident in seen_idents:
+            ident = f"{base_ident}_{n}"
+            n += 1
+        seen_idents.add(ident)
+        if not isinstance(body, dict):
+            body = {}
+        code = body.get("code")
+        if not isinstance(code, str):
+            code = ident.lower()
+        if code in seen_codes:
+            # Fail closed: a synthesized suffix ('a_2') matches no wire value —
+            # a dead member that a closed Literal would then advertise. Corpus
+            # has 0 collisions (2026-06-10 replay); the canonicalizer str-dedupes
+            # codes, so only author-written duplicates can reach this.
+            named = f"enum {enum_name!r}" if enum_name else "enum"
+            raise CodegenError(
+                f"{named} declares duplicate wire code {code!r} (variant {variant!r}); "
+                "give each variant a distinct `code`"
+            )
+        c = code
+        seen_codes.add(c)
+        disp = body.get("display")
+        disp = _as_str(disp)
+        out.append((ident, c, disp))
+    return out
+
+
+def _render_enum(name: str, spec: Dict[str, Any]) -> str:
+    """Emit an ``enum.Enum`` subclass. Values use ``code`` if provided,
+    else the variant identifier. ``display`` lands on a ``.display``
+    property for nicer __str__."""
+    values = spec.get("values") if isinstance(spec, dict) else {}
+    if not isinstance(values, dict) or not values:
+        return f"class {name}(str, enum.Enum):\n    pass"
+    # Case-uniqueness on the RAW declared codes, BEFORE the per-member exact
+    # dedup in ``_enum_members``: two codes differing only by case ('Score' vs
+    # 'score') would both lower()-collide on the wire. Fail closed (corpus has 0
+    # such cases) rather than silently suffix-dropping one — a closed projection
+    # (D5) reads these codes directly, so a case-collision would silently corrupt
+    # the contract.
+    raw_codes = [
+        b["code"] for b in values.values()
+        if isinstance(b, dict) and isinstance(b.get("code"), str)
+    ]
+    lowered = [c.lower() for c in raw_codes]
+    if len(set(lowered)) != len(lowered):
+        raise CodegenError(
+            f"enum {name!r} declares codes colliding under case-fold: {sorted(raw_codes)}"
+        )
+    lines = [f"class {name}(str, enum.Enum):"]
+    displays: Dict[str, str] = {}
+    for ident, c, disp in _enum_members(spec, enum_name=name):
+        lines.append(f"    {ident} = {c!r}")
+        if disp:
+            displays[ident] = disp
+    if displays:
+        lines.append("")
+        lines.append("    @property")
+        lines.append("    def display(self) -> str:")
+        lines.append("        return _DISPLAYS_" + name + ".get(self.name, self.name)")
+        lines.append("")
+        lines.append(f"_DISPLAYS_{name} = {{")
+        for k, v in displays.items():
+            lines.append(f"    {k!r}: {v!r},")
+        lines.append("}")
+    return "\n".join(lines)
+
+
+def _render_error(
+    name: str, spec: Dict[str, Any], input_param_union: Optional[Set[str]] = None
+) -> str:
+    """Emit a typed exception subclass of ParseError with the declared
+    ``carries`` fields as keyword-only init args.
+
+    Also emits ``_CARRY_PARAMS: {attr_ident: wire_param_name}`` for every carry
+    whose name appears in ``input_param_union`` (the schema-wide union of all
+    endpoints' ``input_params`` keys). The runtime's ``_build_error`` hydrates
+    those attrs from the failing call's REQUEST PARAMS — errors are
+    module-global, so there is no owning operation in scope here and the union
+    is the correct (widest-sound) source set. A carry outside the union stays a
+    typed init arg but is omitted from the map: it hydrates to None by design.
+    """
+    when = spec.get("when") if isinstance(spec, dict) else None
+    carries = spec.get("carries") if isinstance(spec, dict) else None
+    if not isinstance(carries, list):
+        carries = []
+    doc = when or f"Raised when the API returns a {name} condition."
+
+    init_args = ["status_code: int = 0", "message: str = ''", "body: Any = None"]
+    body_lines = ["super().__init__(status_code, message, body=body)"]
+    # Sanitize ``carries``: each carry becomes an init arg appended to the fixed
+    # ``[status_code, message, body]``. A carry colliding with a reserved arg
+    # name, or an internal duplicate (after sanitize), would emit
+    # ``SyntaxError: duplicate argument`` at import — and a carry named after
+    # any ParseError BASE attribute (``meta``, ``code``, ``snippet``,
+    # ``upstream_status_code``, ``retry_after``) would be silently clobbered by
+    # the runtime's post-construction finishing, so the reserve set covers the
+    # full base attribute surface. Dedup with a deterministic suffix.
+    reserved_carry: Set[str] = {
+        "self", "status_code", "message", "body",
+        "meta", "retry_after", "code", "snippet", "upstream_status_code",
+    }
+    taken_carry: Set[str] = set()
+    carry_params: List[Tuple[str, str]] = []
+    for c in carries:
+        ident = _allocate_ident(
+            str(c), taken_carry, fallback="extra", reserved=reserved_carry
+        )
+        init_args.append(f"{ident}: Any = None")
+        body_lines.append(f"self.{ident} = {ident}")
+        if input_param_union and str(c) in input_param_union:
+            carry_params.append((ident, str(c)))
+    sig = ", ".join(["self"] + init_args)
+    body = "\n        ".join(body_lines)
+    carry_map_line = ""
+    if carry_params:
+        entries = ", ".join(f"{a!r}: {w!r}" for a, w in carry_params)
+        carry_map_line = (
+            f"    _CARRY_PARAMS: ClassVar[Dict[str, str]] = {{{entries}}}\n"
+        )
+    return (
+        f"class {name}(_ParseError):\n"
+        f"{_docstring(doc)}\n"
+        f"\n"
+        f"{carry_map_line}"
+        f"    def __init__({sig}) -> None:\n"
+        f"        {body}\n"
+    )
+
+
+def _op_param_records(
+    takes: Dict[str, Any],
+    params_for_ep: Dict[str, Any],
+    enum_alloc: Optional[Dict[str, str]] = None,
+    enums: Optional[Dict[str, Any]] = None,
+) -> Tuple[List[Tuple[str, str, bool, Optional[str]]], Dict[str, str]]:
+    """Typed-kwarg signature records for one op: the SINGLE source consumed by
+    the method emitter AND ``op_call_descriptors`` (README Call column), so the
+    two cannot drift.
+
+    Param-ident allocation (P0.3): each ``takes`` KEY (method kwarg) becomes a
+    signature param. A kwarg named after a runtime-structural ident (``self``
+    → ``def search(self, self: …)`` SyntaxError; ``_api`` etc.) or two kwargs
+    sanitizing to one ident must be suffixed, not emitted raw. The
+    ``{method_arg → unique ident}`` map is allocated ONCE so the signature loop
+    AND the body's ``_params`` loop read the SAME idents. ``limit`` is NOT
+    reserved here: a non-paginated op may legitimately take a user-facing
+    ``limit`` kwarg; the synthetic paginator ``limit`` is added by callers only
+    when absent.
+
+    Each record is ``(ident, decl_str, required, description)``, typed by
+    joining the ``takes`` VALUE (endpoint param name) against ``params_for_ep``
+    and sorted required-first ONCE — signature decl order and docstring Args
+    order both derive from it, so the two always match. Expects the
+    paginator-swallowed param to be stripped from ``takes`` by the caller.
+    """
+    param_reserved = _runtime_reserved_member_names()
+    param_taken: Set[str] = set()
+    param_idents: Dict[str, str] = {}
+    for method_arg in takes.keys():
+        param_idents[method_arg] = _allocate_ident(
+            str(method_arg), param_taken, fallback="arg", reserved=param_reserved
+        )
+    records: List[Tuple[str, str, bool, Optional[str]]] = []
+    for method_arg, endpoint_param in takes.items():
+        ident = param_idents[method_arg]
+        info = params_for_ep.get(endpoint_param)
+        anno = _param_annotation(info, enum_alloc, enums)
+        required = bool(isinstance(info, dict) and info.get("required"))
+        desc = info.get("description") if isinstance(info, dict) else None
+        records.append(
+            (ident, _param_decl(ident, anno, required), required,
+             _as_str(desc))
+        )
+    records.sort(key=lambda r: 0 if r[2] else 1)
+    return records, param_idents
+
+
+def _render_operation_method(
+    op_name: str,
+    op: Dict[str, Any],
+    *,
+    parent_kind: str,  # "resource", "collection", "root"
+    params_for_ep: Optional[Dict[str, Any]] = None,
+    method: str = "POST",
+    method_ident: Optional[str] = None,
+    endpoint_description: Optional[str] = None,
+    enum_alloc: Optional[Dict[str, str]] = None,
+    enums: Optional[Dict[str, Any]] = None,
+    element_keyed_by: Optional[Dict[str, Optional[str]]] = None,
+    endpoint_return_schemas: Optional[Dict[str, Any]] = None,
+    resource_field_labels: Optional[Dict[str, Dict[str, str]]] = None,
+) -> str:
+    """Emit one method on a resource / collection / root client.
+
+    Signature comes from ``takes`` (method kwarg → endpoint param name),
+    typed by joining each kwarg's endpoint param (the VALUE in ``takes``)
+    against ``params_for_ep`` — the ``input_params`` map of the op's
+    endpoint. ``pins`` are pre-bound from $self / $arg / literals.
+    Return type comes from ``returns``; pagination wraps in a Paginator
+    when the op declares a ``pagination`` block.
+
+    Typed-param join (this is the M1 change): each kwarg's annotation comes
+    from ``_param_annotation(params_for_ep[endpoint_param])``; required
+    params (``ParamSpec.required``) emit with no default and sort first.
+    The join degrades to ``Any`` on a missing endpoint / param / metadata,
+    so a thin or malformed spec still renders a working (untyped) method.
+    """
+    endpoint = op.get("endpoint")
+    if not isinstance(endpoint, str):
+        return ""  # no-op stub; safer than emitting a broken method
+    # Authoring-time gate: this name is a URL path segment in every emitted
+    # ``_request`` call. The runtime sink quotes it anyway; failing here gives
+    # the agent the actionable signal at draft time, not a 404 at run time.
+    _require_wire_segment(endpoint, "endpoint name")
+    returns = _coerce_type_label(op.get("returns"))
+    takes = op.get("takes")
+    takes = _as_dict(takes)
+    pins = op.get("pins")
+    pins = _as_dict(pins)
+    params_for_ep = _as_dict(params_for_ep)
+    element_keyed_by = _as_dict(element_keyed_by)
+    endpoint_return_schemas = _as_dict(endpoint_return_schemas)
+    # Derived here, not threaded in: every caller passed exactly this — the
+    # op's unwrapped-sample top-level key-set (used by _emit_items' thin
+    # projection). Resolving internally drops a redundant pre-resolution param.
+    sample_keys = _sample_keys_for(endpoint_return_schemas, op)
+
+    # --- Pagination normalization (one decision point) ---------------------
+    # Every list operation is normalized to a single ``scheme`` and rendered
+    # through one ``_fetch_page`` pipeline. The codegen reads the RAW
+    # ``pagination`` dict keys (the cross-repo contract defined canonically in
+    # the parse-core ``PaginationSpec`` model — codegen does not import it).
+    #   * structured block present → its declared ``scheme``
+    #     (single_page/cursor/page/time_cursor)
+    #   * a collection return (``List[X]`` / ``Optional[List[X]]``) with NO
+    #     block → fail-closed (``CodegenError``): the gate should have rejected
+    #     it; codegen refuses to guess the response shape (no legacy fallback).
+    #   * non-collection return → ``None`` (single-resource return, unchanged)
+    _pg_raw = op.get("pagination")
+    pg: Optional[Dict[str, Any]] = _pg_raw if isinstance(_pg_raw, dict) else None
+    is_collection = _is_collection_label(returns)
+    elem = _collection_element(returns)
+    scheme = pg.get("scheme") if pg else None
+    if is_collection and scheme is None:
+        raise CodegenError(
+            f"op {op_name!r} (endpoint {endpoint!r}) returns {returns!r} but has "
+            f"no pagination block (gate should reject; refusing to guess)"
+        )
+
+    # Envelope-return pagination: when ``returns`` is a NON-collection resource
+    # (an envelope) but the op paginates via an ``items_path`` naming one of that
+    # resource's ``List[X]`` fields, the paginator yields ELEMENTS ``X`` — not the
+    # envelope. ``_collection_element`` leaves a bare resource label unchanged, so
+    # without this each row coerces to the envelope husk (whose fields are absent
+    # on a row → ``AttributeError`` on element access). Resolve the element from
+    # the envelope's items_path field type; unresolvable → unchanged (fail-safe).
+    if scheme is not None and not is_collection and resource_field_labels:
+        _items_path = pg.get("items_path") if pg else None
+        if isinstance(_items_path, str) and _items_path and "." not in _items_path:
+            _field_label = resource_field_labels.get(returns, {}).get(_items_path)
+            if isinstance(_field_label, str) and _is_collection_label(_field_label):
+                elem = _collection_element(_field_label)
+
+    # The paginator OWNS the pagination ``request_param``: the scheme arms below
+    # inject/override that wire param on every advance, so a ``takes`` entry
+    # bound to the same endpoint param would emit a user-facing kwarg the
+    # paginator immediately fights (pages 2+ override it; a leaked ``page``/
+    # ``cursor`` kwarg can only skew page 1). Strip such entries from the
+    # emitted surface — the signature, docstring, and body loops below all
+    # derive from ``takes``. Matched on the ENDPOINT-param side (takes maps
+    # method_kwarg → endpoint_param; the kwarg may be renamed). ``single_page``
+    # declares no request_param, so manual-paging takes on a single_page op
+    # (e.g. an explicit offset param) survive untouched.
+    _paginator_param = pg.get("request_param") if pg else None
+    if _paginator_param:
+        takes = {k: v for k, v in takes.items() if v != _paginator_param}
+
+    # Signature records — SINGLE-SOURCED with op_call_descriptors via
+    # ``_op_param_records`` so the README "Call" column cannot drift from the
+    # emitted signature (same consolidation precedent as D4's member
+    # allocation).
+    records, param_idents = _op_param_records(takes, params_for_ep, enum_alloc, enums)
+    arg_names: List[str] = [r[0] for r in records]
+    arg_decls: List[str] = ["self"] + [r[1] for r in records]
+    arg_descs: List[Tuple[str, Optional[str]]] = [(r[0], r[3]) for r in records]
+    has_cap_arg = False
+    has_max_fetches_arg = False
+    if scheme is not None:
+        # Add a synthetic ``limit`` arg to cap the paginator's TOTAL yield at the
+        # call site (optional, trails the typed params). But when the op ALREADY
+        # takes a wire param named ``limit`` (a PER-PAGE size, not a total cap),
+        # do NOT reuse it as the cap: wiring the per-page size into the
+        # Paginator's total-yield ceiling made ``search(limit=N)`` yield N items
+        # and STOP, so the client could never reach page 2. In that case no cap
+        # arg is added and the Paginator gets ``limit=None`` (see the emit below).
+        if "limit" not in arg_names:
+            arg_decls.append("limit: Optional[int] = None")
+            has_cap_arg = True
+        if "max_fetches" not in arg_names:
+            arg_decls.append("max_fetches: int = 1000")
+            has_max_fetches_arg = True
+
+    # Body — build the params dict from takes + pins, call request, coerce.
+    body_lines: List[str] = []
+    body_lines.append("_params: Dict[str, Any] = {}")
+    for method_arg, endpoint_param in takes.items():
+        arg_ident = param_idents[method_arg]
+        body_lines.append(f"if {arg_ident} is not None: _params[{endpoint_param!r}] = {arg_ident}")
+    for endpoint_param, value_expr in pins.items():
+        py_expr = _resolve_param_value(value_expr, self_var="self", op=op_name)
+        # On generated Collection methods, ``self`` is the collection handle and
+        # ``self._parent`` is the resource exposing that collection. The corpus
+        # uses both ``$self.X`` and ``$self.parent.X`` for that owning resource
+        # (e.g. ``post.comments.list`` pins ``post_id`` from ``Post.id``), so the
+        # collection fixup intentionally keeps both spellings on ``self._parent``.
+        _ve = value_expr.strip() if isinstance(value_expr, str) else value_expr
+        if parent_kind == "collection" and _ve in ("$self", "$self.parent"):
+            py_expr = "self._parent"
+        elif (
+            parent_kind == "collection"
+            and isinstance(_ve, str)
+            and _ve.startswith("$self.")
+            and not _ve.startswith("$self.parent.")
+        ):
+            tail = _safe_self_tail(_ve[len("$self."):], op=op_name)
+            py_expr = f"self._parent.{tail}" if tail else "self._parent"
+        body_lines.append(f"_params[{endpoint_param!r}] = {py_expr}")
+
+    # The actual call — through the root API
+    api_attr = "self._api" if parent_kind in ("collection", "resource") else "self"
+    body_lines.append("")
+
+    if scheme is not None:
+        # One ``_fetch_page(_cursor) -> (items, next_cursor)`` pipeline. The
+        # per-scheme arm sets ``items``/``nxt``; the Paginator stops on
+        # ``nxt is None``. Item coercion is shared (``elem`` is the element
+        # type for a ``List[X]`` return, else the bare ``returns`` label).
+        # ``dedup_arg`` is appended to the SHARED ``_Paginator(...)`` emit below;
+        # only the ``time_cursor`` arm sets it (its re-seed-by-boundary advance
+        # can repeat the boundary item on an inclusive-boundary API).
+        assert pg is not None  # scheme is not None ⟹ a pagination block is present
+        # Each known scheme dereferences certain spec fields unguarded; a missing
+        # one would emit silently-broken code (a None ``items_path`` →
+        # ``if None not in _resp`` always raises ``PaginationError``; a None
+        # ``cursor_from_field`` → first-page-only truncation). Fail loud at render
+        # so ``parse sync`` skips+warns the op instead of promoting a broken
+        # module — mirroring the unrecognized-scheme backstop below.
+        _required = {
+            "single_page": ("items_path",),
+            "cursor": ("items_path", "request_param", "next_cursor_path"),
+            "page": ("items_path", "request_param"),
+            "time_cursor": ("items_path", "request_param", "cursor_from_field"),
+        }.get(scheme, ())
+        _missing = [f for f in _required if not pg.get(f)]
+        if _missing:
+            raise CodegenError(
+                f"pagination scheme {scheme!r} for op {endpoint!r} is missing required "
+                f"field(s) {_missing}; codegen refuses to emit a broken paginator"
+            )
+        # time_cursor advances by reading ``cursor_from_field`` off each item, so
+        # the element MUST be a Resource (the emitted body dereferences
+        # ``_coerced[-1]._FIELD_ALIASES`` and ``items[-1].get(...)``). A scalar /
+        # Any element has neither — reject at render rather than emit code that
+        # AttributeErrors at the user's runtime (correct-by-construction: a
+        # cursor-on-a-scalar spec is incoherent, not a runtime contingency).
+        if scheme == "time_cursor" and elem in _KNOWN_FIELD_LEAF_LABELS:
+            raise CodegenError(
+                f"pagination scheme 'time_cursor' for op {endpoint!r} returns a non-Resource "
+                f"element {elem!r}; cursor_from_field {pg.get('cursor_from_field')!r} has no "
+                f"field to read from"
+            )
+
+        dedup_arg = ""
+        # Identity-dedup (page/cursor only): emit ``dedup=True,
+        # identity_dedup=True`` ONLY where the captured sample PROVES the element
+        # key unique (>=2 item rows, all keys present + distinct — the Step-0
+        # ``dedup_eligible`` bucket, ~38 ops corpus-wide). Every other page/cursor
+        # op (keyless / no-sample / <2-row / non-unique) gets NO identity-dedup —
+        # it relies on the loud content-stall guard + the keyless _page_signature
+        # fix (runtime arm). The element's ``keyed_by`` is supplied via the
+        # ``element_keyed_by`` map because it is NOT in the collection emitter's
+        # scope (the element resource's key, not the owning collection's).
+        if scheme in ("cursor", "page") and _dedup_eligible_for(
+            endpoint_return_schemas, op, pg, element_keyed_by, elem
+        ):
+            dedup_arg = ", dedup=True, identity_dedup=True"
+        body_lines.append("def _fetch_page(_cursor: Optional[Any]):")
+        body_lines.append("    _p = dict(_params)")
+
+        if scheme == "single_page":
+            # The whole response is one page: extract the declared ``items_path``
+            # array and never advance. Yields exactly one page through a
+            # ``Paginator[X]``. NEVER coerce the raw dict (that path reaches
+            # ``_unwrap_single_list``); extract the declared key verbatim.
+            items_path: Any = pg.get("items_path")
+            body_lines.append(f"    _resp = {api_attr}._request({method!r}, {endpoint!r}, _p)")
+            body_lines += _emit_items(items_path, sample_keys)
+            # Per-element paginator rows are SEPARATE top-level _coerce
+            # calls (NOT List[X] recursion) at mode='element' — a bad/husk row
+            # degrades to raw, never aborts the page. The strict return verdict
+            # is reserved for the single-resource mode='return' site.
+            body_lines.append(f"    return ([_coerce(_i, {elem!r}, self, mode='element') for _i in items], None)")
+
+        elif scheme == "cursor":
+            request_param: Any = pg.get("request_param")
+            items_path: Any = pg.get("items_path")
+            next_cursor_path = pg.get("next_cursor_path")
+            has_more_path = pg.get("has_more_path")
+            body_lines.append(f"    if _cursor is not None: _p[{request_param!r}] = _cursor")
+            body_lines.append(f"    _resp = {api_attr}._request({method!r}, {endpoint!r}, _p)")
+            body_lines += _emit_items(items_path, sample_keys)
+            # Re-coerce _resp to a dict AFTER extraction so the cursor/has_more
+            # ``.get()`` calls below survive a top-level-list / None body (a list
+            # has no ``.get``). _extract_items already pulled the items from the
+            # raw body; these reads only mine cursor metadata, absent on a list.
+            body_lines.append("    _resp = _resp if isinstance(_resp, dict) else {}")
+            body_lines.append(f"    nxt = {_resp_path_expr(next_cursor_path)}")
+            if has_more_path:
+                body_lines.append(f"    if {_resp_path_expr(has_more_path)} is False: nxt = None")
+            body_lines.append("    if not items: nxt = None")
+            # Per-element rows at mode='element' (lenient degrade-to-raw).
+            body_lines.append(f"    return ([_coerce(_i, {elem!r}, self, mode='element') for _i in items], nxt)")
+
+        elif scheme == "page":
+            request_param: Any = pg.get("request_param")
+            items_path: Any = pg.get("items_path")
+            page_path = pg.get("page_path")
+            total_pages_path = pg.get("total_pages_path")
+            # Base page = the request_param's declared integer ``default`` (0 for
+            # zero-based bwb/HN, 1 for one-based). The gate (Task 13) requires a
+            # declared integer default; codegen defaults to 1 only as a last
+            # resort. Sending the wrong base silently skips the first page.
+            _base = (params_for_ep.get(request_param) or {})
+            _base = _base.get("default") if isinstance(_base, dict) else None
+            _base = _base if isinstance(_base, int) else 1
+            body_lines.append(f"    _page = _cursor if isinstance(_cursor, int) else {_base!r}")
+            body_lines.append(f"    _p[{request_param!r}] = _page")
+            body_lines.append(f"    _resp = {api_attr}._request({method!r}, {endpoint!r}, _p)")
+            body_lines += _emit_items(items_path, sample_keys)
+            # Re-coerce _resp to a dict AFTER extraction so the page/total ``.get()``
+            # calls below survive a top-level-list / None body (a list has no
+            # ``.get``). _extract_items already pulled the items.
+            body_lines.append("    _resp = _resp if isinstance(_resp, dict) else {}")
+            if total_pages_path:
+                body_lines.append(f"    try: _total = int({_resp_path_expr(total_pages_path)})")
+                body_lines.append("    except (TypeError, ValueError): _total = None")
+            else:
+                body_lines.append("    _total = None")
+            if page_path:
+                body_lines.append(f"    try: _cur = int({_resp_path_expr(page_path, '_page')})")
+                body_lines.append("    except (TypeError, ValueError): _cur = None")
+            else:
+                body_lines.append("    _cur = _page")
+            # Base-relative termination: a zero-based API on its last page reports
+            # _cur = _base + (_total - 1), so (_cur - _base + 1) >= _total stops
+            # after the last page regardless of base (no off-by-one over-fetch).
+            body_lines.append("    if not items: nxt = None")
+            body_lines.append(f"    elif _total is not None and _cur is not None and (_cur - {_base!r} + 1) >= _total: nxt = None")
+            body_lines.append("    else: nxt = (_cur + 1) if _cur is not None else (_page + 1)")
+            # Per-element rows at mode='element' (lenient degrade-to-raw).
+            body_lines.append(f"    return ([_coerce(_i, {elem!r}, self, mode='element') for _i in items], nxt)")
+
+        elif scheme == "time_cursor":
+            request_param: Any = pg.get("request_param")
+            items_path: Any = pg.get("items_path")
+            cursor_from_field = pg.get("cursor_from_field")
+            # Dedup-by-identity: an inclusive-boundary API repeats the boundary
+            # item across pages; the runtime drops already-seen items (by
+            # _Resource identity) and stops on a 0-new page. ``dedup=True`` is a
+            # literal — no keyed_by threading needed (identity eq/hash key on
+            # _KEY_FIELD already).
+            dedup_arg = ", dedup=True"
+            body_lines.append(f"    if _cursor is not None: _p[{request_param!r}] = _cursor")
+            body_lines.append(f"    _resp = {api_attr}._request({method!r}, {endpoint!r}, _p)")
+            body_lines += _emit_items(items_path, sample_keys)
+            # Per-element rows at mode='element' (lenient degrade-to-raw).
+            body_lines.append(f"    _coerced = [_coerce(_i, {elem!r}, self, mode='element') for _i in items]")
+            # Re-seed from the RAW wire value, not the coerced attribute: a
+            # coercing cursor field (datetime/Decimal/…) would otherwise send the
+            # coerced object back to the API (e.g. a datetime isoformatted onto an
+            # integer param). Resolve cursor_from_field → wire key via the element's
+            # _FIELD_ALIASES (same `.get(name, name)` _from_payload uses), so an
+            # aliased field reads its wire key, not the python name.
+            body_lines.append("    _last = _coerced[-1] if _coerced else None")
+            body_lines.append("    if isinstance(_last, _Resource) and isinstance(items[-1], dict):")
+            body_lines.append(
+                f"        nxt = items[-1].get(_last._FIELD_ALIASES.get({cursor_from_field!r}, {cursor_from_field!r}))"
+            )
+            body_lines.append("    else:")
+            body_lines.append("        nxt = None")
+            body_lines.append("    return (_coerced, nxt)")
+
+        else:
+            # An unrecognized scheme reached codegen — fail-closed rather than
+            # fall back to ``_coerce(_resp, "List[X]")`` (that path reaches
+            # ``_unwrap_single_list`` and silently single-pages). The gate
+            # rejects unknown schemes pre-render; this is the codegen backstop.
+            raise CodegenError(
+                f"unrecognized pagination scheme {scheme!r} on op {op_name!r} "
+                f"(endpoint {endpoint!r}) — known schemes: single_page, cursor, "
+                f"page, time_cursor"
+            )
+
+        # A wire ``limit`` param is a per-page size, NOT the paginator's total
+        # cap — emit ``limit=None`` so it cannot truncate the stream at one page
+        # (Fix B). Only the synthetic cap arg (added above when no wire ``limit``)
+        # bounds the total yield.
+        _cap = "limit" if has_cap_arg else "None"
+        max_fetches_expr = "max_fetches" if has_max_fetches_arg else "1000"
+        body_lines.append(
+            f"return _Paginator(_fetch_page, limit={_cap}, max_fetches={max_fetches_expr}{dedup_arg}, _api={api_attr})"
+        )
+        # Emit _Paginator[Element] so `for x in api.things.search()` widens
+        # the loop variable to the element type, not Any. The element comes
+        # from the ``List[X]`` / ``Optional[List[X]]`` return (unified to X);
+        # for non-collection returns we fall back to bare _Paginator. The
+        # reserved alias guards against a domain resource named ``Paginator``
+        # shadowing the runtime base.
+        # ``elem`` is an agent-authored label reaching an ANNOTATION position
+        # (``_Paginator[{elem}]``) raw — gate it the SAME way fields are
+        # (`_is_well_formed_annotation`) so a hostile label (`List[X]: pass\n…`)
+        # degrades to a bare ``_Paginator`` instead of injecting source. (The
+        # ``_coerce(_i, {elem!r}, …)`` use is repr'd, already safe.)
+        if is_collection and _is_well_formed_annotation(elem):
+            return_anno = f"_Paginator[{elem}]"
+        else:
+            return_anno = "_Paginator"
+    else:
+        body_lines.append(f"_resp = {api_attr}._request({method!r}, {endpoint!r}, _params)")
+        # A single-resource return crosses the return-type contract boundary,
+        # so emit mode='return' — the strict husk/scalar fail-loud verdicts fire
+        # here (and ONLY in regenerated modules; old 3-arg callers keep the
+        # lenient default). List[X] / Dict / Optional inner recursion flips back
+        # to boundary=False inside coerce(), so element disposition stays lenient.
+        body_lines.append(f"return _coerce(_resp, {returns!r}, self, mode='return')")
+        # ``returns`` reaches the ``-> {return_anno}:`` annotation position raw;
+        # gate it like fields so a hostile label degrades to ``Any`` rather than
+        # breaking out of the annotation and injecting a class-body statement
+        # (``from __future__ import annotations`` does NOT protect — the payload
+        # injects a sibling statement, it never evaluates the annotation). The
+        # ``_coerce(_resp, {returns!r}, …)`` use is repr'd, already safe.
+        return_anno = returns if _is_well_formed_annotation(returns) else "Any"
+
+    sig = ", ".join(arg_decls)
+    indented_body = "\n        ".join(body_lines)
+    # The method name is allocated by the caller's per-resource member namespace
+    # (P0.4) when provided; collections allocate their own (no field/sub clash).
+    method_name = method_ident or _safe_ident(op_name, fallback="call")
+    docstring = _render_method_docstring(op, arg_descs, endpoint_description)
+    return (
+        f"    def {method_name}({sig}) -> {return_anno}:\n"
+        f"{docstring}"
+        f"        {indented_body}\n"
+    )
+
+
+def _render_method_docstring(
+    op: Dict[str, Any],
+    arg_descs: List[Tuple[str, Optional[str]]],
+    endpoint_description: Optional[str] = None,
+) -> str:
+    """Build the method docstring block (indented, trailing newline).
+
+    Carries the operation's narrative — the ``description`` of the endpoint it
+    calls (resolved by the caller via ``endpoint_description_map`` and passed in
+    as ``endpoint_description``) — plus a Google-style ``Args:`` block listing
+    each typed param's ``description``. A literal op ``description`` (legacy;
+    gate-rejected for new specs) still takes precedence; otherwise the endpoint
+    description is the single source. This is the non-brittle home for the prose
+    the typed signature intentionally drops. Returns ``""`` when there is
+    nothing to document.
+    """
+    summary = op.get("description") or endpoint_description
+    summary = summary.strip() if isinstance(summary, str) else ""
+    documented = [(ident, d.strip()) for ident, d in arg_descs if d and d.strip()]
+    if not summary and not documented:
+        return ""
+
+    lines: List[str] = []
+    if summary:
+        lines.append(summary)
+    if documented:
+        if summary:
+            lines.append("")
+        lines.append("Args:")
+        for ident, desc in documented:
+            lines.append(f"    {ident}: {desc}")
+
+    # Route through the shared safe-docstring helper (block form + backslash /
+    # triple-quote escaping) so no emitter hand-builds a docstring literal.
+    return _docstring("\n".join(lines), indent="        ") + "\n"
+
+
+def _render_resource_class(
+    name: str,
+    spec: Dict[str, Any],
+    *,
+    res_key: str,
+    names: "_ModuleNames",
+    enum_alloc: Optional[Dict[str, str]] = None,
+    enums: Optional[Dict[str, Any]] = None,
+    endpoint_input_params: Optional[Dict[str, Dict[str, Any]]] = None,
+    endpoint_methods: Optional[Dict[str, str]] = None,
+    endpoint_descriptions: Optional[Dict[str, str]] = None,
+    endpoint_return_schemas: Optional[Dict[str, Any]] = None,
+    element_keyed_by: Optional[Dict[str, Optional[str]]] = None,
+    resource_names: Optional[Set[str]] = None,
+    enum_names: Optional[Set[str]] = None,
+    resource_field_labels: Optional[Dict[str, Dict[str, str]]] = None,
+) -> str:
+    """Emit a Resource subclass with fields, operations, and sub-resource
+    property accessors.
+
+    ``res_key`` is the resource's spec key; ``names`` is the module-level
+    name allocator (P0.2) — the sub-resource collection class names are read
+    from it so a ``_camel`` collision between two sub-resources doesn't emit a
+    duplicate class + duplicate property.
+
+    ``endpoint_input_params`` is the ``{endpoint_name: input_params}`` lookup
+    threaded from ``render_module`` so each operation method can type its
+    kwargs from the matching endpoint's params. ``endpoint_methods`` is the
+    parallel ``{endpoint_name: HTTP method}`` lookup so each method emits the
+    real verb.
+
+    ``resource_names`` / ``enum_names`` are the FULL emitted (ALLOCATED) name
+    sets for the module — the field-annotation resolvability gate validates
+    every field's annotation against them, degrading an unresolvable or hostile
+    label to ``Any``. They derive from the allocator's VALUES (not a fresh
+    ``_camel`` comprehension) so a suffixed resource/enum doesn't silently
+    degrade a referencing field to ``Any``.
+
+    Member-namespace reservation (P0.4): fields, operation methods, and
+    sub-resource accessors all land on ONE class namespace. A field, an op, and
+    a sub-resource sharing a name (``comments``) would emit three same-named
+    members — Python keeps the last, the others' behavior is wrong. We allocate
+    one per-resource member namespace, seeded with the runtime-structural
+    reserved names, with precedence sub-resource > operation > field (the loser
+    is suffixed; a suffixed FIELD keeps its wire read via ``_FIELD_ALIASES``).
+    """
+    endpoint_input_params = endpoint_input_params or {}
+    endpoint_methods = endpoint_methods or {}
+    endpoint_descriptions = endpoint_descriptions or {}
+    endpoint_return_schemas = endpoint_return_schemas or {}
+    element_keyed_by = element_keyed_by or {}
+    resource_names = resource_names or set()
+    enum_names = enum_names or set()
+    enum_alloc = enum_alloc or {}
+    fields = spec.get("fields")
+    fields = _as_dict(fields)
+    keyed_by = spec.get("keyed_by")
+    keyed_by = _as_str(keyed_by)
+    constructible = bool(spec.get("constructible"))
+    operations = spec.get("operations")
+    operations = _as_dict(operations)
+    sub_resources = spec.get("sub_resources")
+    sub_resources = _as_dict(sub_resources)
+
+    reserved = _runtime_reserved_member_names()
+    # ONE member namespace for this class — shared single source with
+    # ``op_call_descriptors`` (which previously re-ran these loops by hand,
+    # "byte-for-byte"). Precedence contract lives in ``_member_allocation``.
+    sub_attrs, op_idents, field_idents = _member_allocation(
+        operations, sub_resources, fields, reserved=reserved
+    )
+    # Insertion order of ``op_idents`` IS the emit order (dicts preserve it).
+    emitted_ops: List[str] = list(op_idents)
+
+    # Walk fields once — extract type label (with enum override), aliases. Record
+    # the real wire name in _FIELD_ALIASES whenever the allocated ident differs
+    # from the wire name (a sanitize/collision/reserved suffix), so _from_payload
+    # reads the wire key.
+    typed_fields: Dict[str, str] = {}
+    aliases: Dict[str, str] = {}
+    for fname, fval in fields.items():
+        type_label, enum_binding, alias_from = _extract_field_spec(fval)
+        # An enum-bound field is OPEN — ``Enum | str`` (D2): output values are
+        # observed, not contract-bound, so tolerant coercion maps an observed
+        # value to the member and keeps an unobserved-but-valid value RAW rather
+        # than type-rejecting it. Under single-source coercion the runtime
+        # resolves this annotation; the resolvability gate below degrades a
+        # DANGLING enum binding (no matching emitted enum) to Any.
+        if enum_binding:
+            # Resolve the binding to the enum's ALLOCATED name (a collision
+            # suffix can move it off ``_camel(enum_binding)``); the
+            # resolvability gate keys on allocated names, so an unresolved
+            # binding would wrongly degrade to ``Any``.
+            enum_class = enum_alloc.get(_camel(enum_binding), _camel(enum_binding))
+            typed_fields[fname] = f"{enum_class} | str"
+        else:
+            typed_fields[fname] = _coerce_type_label(type_label)
+        ident = field_idents[fname]
+        # Explicit alias wins; else if the ident was suffixed/sanitized away from
+        # the wire name, record the wire name so the value isn't lost.
+        if alias_from:
+            aliases[ident] = alias_from
+        elif ident != fname:
+            aliases[ident] = fname
+
+    # Flat-inheritance invariant (paired with ``Resource._field_hints``'s
+    # own-annotations filter): every resource class derives DIRECTLY from
+    # ``_Resource`` — single-level. There is no ``extends``/``base`` spec key
+    # that would introduce a parent resource, so the runtime's own-class hint
+    # filter is correct-by-construction and needs no MRO walk. Assert the spec
+    # carries no such key at the single emission site, so a future spec-contract
+    # addition can't silently break the filter's assumption.
+    if "extends" in spec or "base" in spec:
+        # A bare assert is stripped under ``-O`` — this guard must survive it.
+        raise CodegenError(
+            "resource spec introduced inheritance (extends/base) — the flat-base "
+            "invariant in Resource._field_hints no longer holds; add an MRO walk"
+        )
+    lines: List[str] = []
+    lines.append(f"class {name}(_Resource):")
+    # Class docstring — the durable home for per-field reference text. PEP-526
+    # bare annotations (``title: str``) can't carry a runtime attribute
+    # docstring, so documented fields are collected into a Google-style
+    # ``Fields:`` block here (read order = spec order). Emitted only when at
+    # least one field declares a ``description``; routed through the shared
+    # safe-docstring helper. It is the FIRST statement in the class body, so a
+    # field annotation can still follow it (a docstring + annotations is valid).
+    _doc_fields = [(field_idents[fn], _field_description(fv))
+                   for fn, fv in fields.items()]
+    _doc_fields = [(ident, d) for ident, d in _doc_fields if d]
+    if _doc_fields:
+        _cls_lines = ["Fields:"]
+        for ident, desc in _doc_fields:
+            _cls_lines.append(f"    {ident}: {desc}")
+        lines.append(_docstring("\n".join(_cls_lines), indent="    "))
+    # PEP-526 field annotations are the SINGLE per-field type source: they
+    # drive both static analysis (pyright sees ``story.title: str``) AND
+    # runtime per-field coercion (``get_type_hints`` at first construction).
+    #
+    # Each annotation is gated for resolvability + injection: an unresolvable
+    # name (dangling enum/resource ref, incl. an unresolvable inner name) or a
+    # hostile/composite-malformed label degrades to ``Any`` so the module
+    # imports and the runtime resolution never NameError-poisons the class.
+    for fname in fields.keys():
+        ident = field_idents[fname]
+        anno = _field_annotation(
+            typed_fields[fname], resource_names=resource_names, enum_names=enum_names
+        )
+        lines.append(f"    {ident}: {anno}")
+    lines.append(f"    _RESOURCE_NAME = {name!r}")
+    # keyed_by ∈ fields invariant: under single-source coercion, __init__ only
+    # sets annotated fields, so a _KEY_FIELD naming an ABSENT field points at a
+    # never-set attribute → pagination false-positives + broken eq/hash/factory.
+    # Emit None when the key isn't a declared field. Test MEMBERSHIP in the
+    # shared field-ident map (not truthiness) so a declared key whose wire name
+    # sanitizes to empty (``""``) still resolves to its real allocated ident.
+    # A container-typed key (List/Dict/…, even Optional-wrapped) is demoted to
+    # value-object semantics (``_KEY_FIELD = None``): hashing a container key
+    # raises ``TypeError`` at runtime (_runtime ``__hash__``), and a container
+    # is not an identity. An ``Optional[scalar]`` key KEEPS its ``_KEY_FIELD``
+    # — the runtime identity-key guard skips identity on null values per
+    # instance instead of demoting the whole resource.
+    _kb_is_container = (
+        keyed_by is not None
+        and keyed_by in typed_fields
+        and _is_container_field_label(typed_fields[keyed_by])
+    )
+    if keyed_by is not None and keyed_by in field_idents and not _kb_is_container:
+        lines.append(f"    _KEY_FIELD = {field_idents[keyed_by]!r}")
+    else:
+        lines.append("    _KEY_FIELD = None")
+    if aliases:
+        alias_lit = "{" + ", ".join(
+            f"{k!r}: {v!r}" for k, v in aliases.items()
+        ) + "}"
+        lines.append(f"    _FIELD_ALIASES = {alias_lit}")
+    if constructible:
+        lines.append("    _CONSTRUCTIBLE = True")
+
+    # Instance methods — pinless (lookup/factory) ops were already filtered out
+    # of ``emitted_ops`` (so their member slots weren't reserved).
+    for op_name in emitted_ops:
+        op_body = operations[op_name]
+        method_src = _render_operation_method(
+            op_name, op_body,
+            parent_kind="resource",
+            params_for_ep=_params_for(endpoint_input_params, op_body),
+            method=_method_for(endpoint_methods, op_body),
+            endpoint_description=_desc_for(endpoint_descriptions, op_body),
+            method_ident=op_idents[op_name],
+            enum_alloc=enum_alloc,
+            enums=enums,
+            element_keyed_by=element_keyed_by,
+            endpoint_return_schemas=endpoint_return_schemas,
+            resource_field_labels=resource_field_labels,
+        )
+        if method_src:
+            lines.append("")
+            lines.append(method_src.rstrip())
+
+    # Sub-resource properties — each backs a per-class Collection subclass whose
+    # name comes from the module allocator (dup-safe across colliding subs).
+    for sub_name, sub_body in sub_resources.items():
+        if not isinstance(sub_body, dict):
+            continue
+        coll_class_name = names.sub_collections[(res_key, sub_name)]
+        attr = sub_attrs[sub_name]
+        lines.append("")
+        lines.append(f"    @property")
+        lines.append(f"    def {attr}(self) -> '{coll_class_name}':")
+        lines.append(f"        _stash = getattr(self, '_sub_{attr}', None)")
+        lines.append(f"        if _stash is None:")
+        lines.append(f"            _stash = {coll_class_name}(_api=self._api, _parent=self)")
+        lines.append(f"            object.__setattr__(self, '_sub_{attr}', _stash)")
+        lines.append(f"        return _stash")
+
+    return "\n".join(lines)
+
+
+def _collection_op_idents(
+    op_names: List[str], *, reserved: Set[str]
+) -> Dict[str, str]:
+    """``{op name → unique method ident}`` for one collection class, so two ops
+    whose names ``_safe_ident``-collapse don't emit duplicate methods (Python
+    keeps the last). Reserves the runtime-structural ``_Collection`` members."""
+    taken: Set[str] = set()
+    out: Dict[str, str] = {}
+    for op_name in op_names:
+        out[op_name] = _allocate_ident(op_name, taken, fallback="call", reserved=reserved)
+    return out
+
+
+@functools.lru_cache(maxsize=1)
+def _collection_reserved() -> Set[str]:
+    # Cached like _runtime_reserved_member_names: constant per process,
+    # previously recomputed per rendered collection. Read-only for callers.
+    from parse_sdk._runtime import Collection as _Collection
+
+    return set(dir(_Collection)) | {"self", "_api", "_parent"}
+
+
+def _render_collection(
+    coll_class_name: str,
+    emit_ops: List[str],
+    operations: Dict[str, Any],
+    *,
+    endpoint_input_params: Optional[Dict[str, Dict[str, Any]]] = None,
+    endpoint_methods: Optional[Dict[str, str]] = None,
+    endpoint_descriptions: Optional[Dict[str, str]] = None,
+    endpoint_return_schemas: Optional[Dict[str, Any]] = None,
+    element_keyed_by: Optional[Dict[str, Optional[str]]] = None,
+    enum_alloc: Optional[Dict[str, str]] = None,
+    enums: Optional[Dict[str, Any]] = None,
+    resource_field_labels: Optional[Dict[str, Dict[str, str]]] = None,
+) -> str:
+    """Emit ONE Collection subclass — the single emitter behind both the
+    sub-resource collections (``PostCommentsCollection``: every dict-valued
+    op) and the root collections (``RedditPostsCollection``: the pinless
+    ``_root_collection_emit_ops`` single source). The caller owns the emit-op
+    selection; everything below it — ident allocation, method rendering, the
+    empty-body ``pass`` fallback — is identical by construction instead of
+    maintained in two near-duplicate renderers.
+
+    ``coll_class_name`` is the module-allocated class name (dup-safe across
+    colliding sub-resources / a root collision with anything prior)."""
+    endpoint_input_params = endpoint_input_params or {}
+    endpoint_methods = endpoint_methods or {}
+    endpoint_descriptions = endpoint_descriptions or {}
+    endpoint_return_schemas = endpoint_return_schemas or {}
+    element_keyed_by = element_keyed_by or {}
+    lines = [f"class {coll_class_name}(_Collection):"]
+    op_idents = _collection_op_idents(emit_ops, reserved=_collection_reserved())
+    emitted = False
+    for op_name in emit_ops:
+        method_src = _render_operation_method(
+            op_name, operations[op_name],
+            parent_kind="collection",
+            params_for_ep=_params_for(endpoint_input_params, operations[op_name]),
+            method=_method_for(endpoint_methods, operations[op_name]),
+            endpoint_description=_desc_for(endpoint_descriptions, operations[op_name]),
+            method_ident=op_idents[op_name],
+            enum_alloc=enum_alloc,
+            enums=enums,
+            element_keyed_by=element_keyed_by,
+            endpoint_return_schemas=endpoint_return_schemas,
+            resource_field_labels=resource_field_labels,
+        )
+        if method_src:
+            lines.append(method_src.rstrip())
+            emitted = True
+    # Empty body when every op was skipped (no ops, or — root case — all
+    # $self-pinned) → ``pass`` keeps the class syntactically valid.
+    if not emitted:
+        lines.append("    pass")
+    return "\n".join(lines)
+
+
+# ONLY genuinely-irregular plurals belong here — ones the closed suffix
+# heuristic in ``_pluralize`` cannot reproduce. Do NOT add convenience entries:
+# regulars like ``category→categories`` or ``site→sites`` are already produced by
+# the heuristic, and listing them here masks heuristic gaps and invites the
+# whack-a-mole ``_pluralize`` warns against. A resource needing a bespoke plural
+# declares ``plural`` in its spec.
+_IRREGULAR_PLURALS = {
+    "person": "people",
+    "child": "children",
+}
+
+
+def _pluralize(name: str) -> str:
+    """Default accessor plural — a CLOSED heuristic. Do NOT add rules here:
+    suffix rules are whack-a-mole (a broad ``-is`` rule garbles Iris/Tennis the
+    way the old ``+es`` garbled Analysis). A resource needing a different
+    plural declares ``plural`` in its spec (read by ``_plural_for``) — naming
+    is spec-owned; this is only the fallback."""
+    low = name.lower()
+    if low in _IRREGULAR_PLURALS:
+        return _IRREGULAR_PLURALS[low]
+    if low.endswith("series"):                        # invariant: Series, TimeSeries, …
+        return low
+    if low.endswith(("sis", "xis")):                  # analysis→analyses, axis→axes
+        return low[:-2] + "es"
+    if low.endswith("z") and not low.endswith("zz"):  # quiz→quizzes (jazz keeps +s)
+        return low + "zes"
+    if low.endswith("y") and len(low) > 1 and low[-2] not in "aeiou":
+        return low[:-1] + "ies"
+    if low.endswith(("s", "x", "ch", "sh")):
+        return low + "es"
+    return low + "s"
+
+
+def _plural_attr(res_cls: str, rspec: Any) -> str:
+    """The attr-safe accessor plural for a resource: spec-owned override first
+    (``plural`` on the resource spec), else the closed heuristic — sanitized
+    through ``_safe_ident`` HERE (the single site) so an override can never
+    inject an unsafe identifier and call sites can't drift on the wrapping.
+
+    The plural heuristic is fed ``_snake(res_cls)`` so a Pascal/camelCase class name
+    pluralizes on a WORD boundary — ``BankAccount`` → ``bank_accounts``,
+    ``ItemSummary`` → ``item_summaries``, ``Series`` → ``series`` (not the old
+    boundary-less ``bankaccounts`` / ``serieses``). A spec-owned ``plural``
+    override is verbatim (user-declared), so it bypasses ``_snake``. This is the
+    SINGLE site behind all three accessor uses (the root-client collection attr,
+    ``op_call_descriptors`` fallback, and ``_factory_rows`` fallback), so the
+    three can never drift on the boundary fix.
+    """
+    p = rspec.get("plural") if isinstance(rspec, dict) else None
+    raw = p.strip() if isinstance(p, str) and p.strip() else _pluralize(_snake(res_cls))
+    return _safe_ident(raw.lower(), fallback="things")
+
+
+def _factory_key_annotation(res_spec: Dict[str, Any], keyed_by: str) -> str:
+    """Annotation for a constructible resource's factory key param.
+
+    Types from the keyed_by field's declared type, gated to known scalar
+    labels only (a constructible key is always a scalar). A composite /
+    unknown label degrades to ``Any`` — never injected into the annotation,
+    which a malformed value (``List[evil')]``) could otherwise turn into a
+    module ``SyntaxError``.
+    """
+    fields = res_spec.get("fields")
+    fields = _as_dict(fields)
+    type_label, _enum, _alias = _extract_field_spec(fields.get(keyed_by))
+    coerced = _coerce_type_label(type_label)
+    if coerced in _KNOWN_PARAM_LABELS:
+        return _annotation_label(coerced)
+    return "Any"
+
+
+def _render_root_client(
+    root_name: str,
+    schema: Dict[str, Any],
+    root_collections: List[Tuple[str, str]],  # [(attr, coll_class_name), ...]
+    root_factories: List[Tuple[str, str, str, str]],  # [(attr, ResourceClass, key_ident, key_anno), ...]
+    error_classes: Optional[List[Tuple[str, str]]] = None,  # [(code, AllocatedClassName), ...]
+) -> str:
+    """Emit the root client class (Reddit / Craigslist / ...).
+
+    ``root_factories`` are no-network constructible-resource accessors —
+    ``reddit.subreddit("learnmachinelearning")`` builds a ``Subreddit`` handle
+    so the navigable idiom ``.subreddit(...).search_posts(...)`` works without
+    a fetch. The key param is required + typed; construction uses keyword args
+    (matching ``Resource.__init__(self, *, _api, _parent=None, **fields)``).
+
+    ``error_classes`` is ``[(wire_kind, AllocatedErrorClassName), ...]`` for
+    every ``ErrorSpec`` that declared a ``code``. It is emitted as the
+    ``_ERROR_CLASSES`` ClassVar (mirroring ``SCRAPER_ID``); ``_request`` forwards
+    it to ``_build_error`` so a wire ``kind`` raises the domain error class. The
+    gate guarantees each ``code`` is unique per API, so the dict is unambiguous.
+    """
+    # Cosmetic docstring text: a non-string description/name degrades to empty
+    # rather than crashing (.strip() on a non-str) — don't skip a whole working
+    # API over a malformed cosmetic field.
+    _desc_src = schema.get("description") or schema.get("name") or ""
+    desc = (_desc_src if isinstance(_desc_src, str) else "").strip()
+    lines = [f"class {root_name}(_BaseAPI):"]
+    if desc:
+        # Route through the shared safe-docstring helper (block form) so a
+        # description ending in a bare ``"`` / backslash can't produce an
+        # unterminated literal that fails the whole module's import (P0.1).
+        lines.append(_docstring(desc))
+    lines.append(f"    SCRAPER_ID: ClassVar[str] = {schema['id']!r}")
+    # Pinned marketplace canonical: bake the recorded snapshot version so the
+    # client sends API-Snapshot-Version on every call (execution stays frozen to
+    # that release). Emitted ONLY when the CLI stamped `_pinned_version` (a
+    # positive int) — account/owned APIs omit it, so their output is unchanged.
+    _pin = schema.get("_pinned_version")
+    if isinstance(_pin, int) and not isinstance(_pin, bool) and _pin >= 1:
+        lines.append(f"    PINNED_VERSION: ClassVar[Optional[int]] = {_pin}")
+    if error_classes:
+        entries = ", ".join(f"{code!r}: {cls}" for code, cls in error_classes)
+        lines.append(f"    _ERROR_CLASSES: ClassVar[Dict[str, type]] = {{{entries}}}")
+    for attr, coll_cls in root_collections:
+        lines.append("")
+        lines.append(f"    @property")
+        lines.append(f"    def {attr}(self) -> '{coll_cls}':")
+        lines.append(f"        return {coll_cls}(_api=self, _parent=None)")
+    for attr, res_cls, key_ident, key_anno in root_factories:
+        lines.append("")
+        lines.append(f"    def {attr}(self, {key_ident}: {key_anno}) -> '{res_cls}':")
+        lines.append(f"        return {res_cls}(_api=self, {key_ident}={key_ident})")
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Top-level entry point
+# ---------------------------------------------------------------------------
+
+
+def _normalize_schema(schema: Dict[str, Any]) -> Dict[str, Any]:
+    """Cross-SDK consistency pass on the schema before render.
+
+    Mutates a shallow copy of the schema:
+      * Enum naming: ``SortBy``/``SortOrder`` → ``Sort``. Any field that
+        used the old name as an enum binding gets rewritten.
+      * Canonical fetcher: when a resource declares ``fetched_by``, ensure
+        the matching op is also reachable as ``.get(<keyed_by>=...)`` on
+        the root collection. (If a ``get`` op already exists, leave it.)
+      * Pagination is NOT normalized here. A ``returns: "List[X]"`` op with no
+        ``pagination`` block fails closed at render (``CodegenError``; ``parse
+        sync`` skips+warns it), and the preview/complete gates reject it at
+        authoring time — so a blockless list op never silently renders.
+    """
+    schema = dict(schema)  # shallow copy — we'll deep-copy mutable nested bits below
+
+    # Endpoint-shape normalization (Option B, locus-internal).
+    # Two of the four schema-build paths that reach render_module (preview's
+    # ``_schema_from_draft`` and the complete-time gate) pass RAW ``apis`` keyed
+    # ``endpoint_name`` with no ``name`` — which every ``ep['name']`` index below
+    # silently drops, starving the typed-signature join AND the sample
+    # reconciliation. Normalize raw endpoints to the executor's ``name`` shape
+    # here so all four paths render identically. We also detach each endpoint's
+    # param dicts up front because later enum rewrites are local to the
+    # normalized schema, never the caller's stored spec.
+    raw_eps = schema.get("endpoints") or []
+    if isinstance(raw_eps, list):
+        projected_eps: List[Any] = []
+        for e in raw_eps:
+            if not isinstance(e, dict):
+                projected_eps.append(e)
+                continue
+            ep = dict(e)
+            is_raw_endpoint = not ep.get("name") and ep.get("endpoint_name")
+            if is_raw_endpoint:
+                ep["name"] = ep.get("endpoint_name")
+                ep["method"] = str(ep.get("method") or "POST").upper()
+            ip = ep.get("input_params")
+            if isinstance(ip, dict):
+                params: Dict[str, Any] = {}
+                for k, v in ip.items():
+                    if isinstance(v, dict):
+                        params[k] = dict(v)
+                    elif is_raw_endpoint:
+                        params[k] = {"type": "string", "description": str(v)}
+                    else:
+                        params[k] = v
+                ep["input_params"] = params
+            if is_raw_endpoint:
+                rs = ep.get("return_schema")
+                ep["return_schema"] = rs if isinstance(rs, dict) else None
+            projected_eps.append(ep)
+        schema["endpoints"] = projected_eps
+
+    # Enum names pass through VERBATIM. The consumer-side canonicalizer (Parse
+    # repo, ``canonicalize_closed_enums``) is the single owner of enum naming;
+    # its contract is spec-name == emitted-name (its ``_camel`` clone +
+    # ``test_camel_matches_sdk`` depend on it).
+    # Fail closed on a non-dict enums (a list/scalar would crash dict() with an
+    # uncaught ValueError/TypeError, OR silently drop the API's enum types).
+    _enums = schema.get("enums")
+    if _enums is not None and not isinstance(_enums, dict):
+        raise CodegenError(f"schema enums must be a mapping, got {type(_enums).__name__}")
+    enums = dict(_enums or {})
+    schema["enums"] = enums
+
+    # Canonical fetcher: synthesize a typed ``.get(<keyed_by>=...)`` on the
+    # root collection ONLY for a genuine point-lookup.
+    #
+    # ``fetched_by`` is dual-spelled: it holds either an OP NAME (reddit
+    # ``Post.fetched_by == "search"``, an op whose endpoint is ``search_posts``)
+    # or an ENDPOINT NAME directly (RS ``fetched_by == "get_post"``). Resolve it
+    # to a concrete endpoint, then gate the synthesis on the endpoint actually
+    # accepting the key — a search-style endpoint (``search_posts`` / ``search``)
+    # does NOT take ``id``, so it's no point-lookup and we synthesize nothing
+    # (leaving navigation to the constructible factory + search). HN/airbnb
+    # never reach the synthesis: they declare their own ``get`` op, short-
+    # circuited by ``if "get" in ops`` below.
+    #
+    # The key param types itself from the resolved endpoint's ParamSpec in
+    # ``_render_operation_method`` (the gate guarantees ``keyed_by`` is a real
+    # param of that endpoint under its own name) — never ``Any``.
+    endpoint_input_params: Dict[str, Dict[str, Any]] = {
+        ep["name"]: (ep.get("input_params") or {})
+        for ep in schema.get("endpoints", [])
+        if isinstance(ep, dict) and isinstance(ep.get("name"), str)
+    }
+    resources = dict(schema.get("resources") or {})
+    for rname, rspec in resources.items():
+        if not isinstance(rspec, dict):
+            continue
+        fetched_by = rspec.get("fetched_by")
+        keyed_by = rspec.get("keyed_by")
+        if not (isinstance(fetched_by, str) and isinstance(keyed_by, str)):
+            continue
+        ops = dict(rspec.get("operations") or {})
+        if "get" in ops:
+            continue  # spec already has it
+        # Resolve fetched_by → concrete endpoint, handling both spellings.
+        if fetched_by in ops and isinstance(ops[fetched_by], dict):
+            endpoint = ops[fetched_by].get("endpoint")
+        else:
+            endpoint = fetched_by
+        if not isinstance(endpoint, str):
+            continue
+        # Gate: only a genuine point-lookup (the endpoint accepts the key).
+        if keyed_by not in (endpoint_input_params.get(endpoint) or {}):
+            continue
+        ops["get"] = {
+            "endpoint": endpoint,
+            "returns": _camel(rname),
+            "takes": {keyed_by: keyed_by},
+        }
+        rspec = {**rspec, "operations": ops}
+        resources[rname] = rspec
+    schema["resources"] = resources
+
+    # Field-type reconciliation — floor a field whose declared
+    # type contradicts the captured sample to the sample-gate's Dict[str,Any]
+    # form (copy-on-write, so the stored spec stays raw). Lives in the focused
+    # ``codegen_reconcile`` sibling, called here as one named pass; lazily
+    # imported (codegen_reconcile back-imports this module) to stay cycle-safe.
+    from parse_sdk import codegen_reconcile as _reconcile
+    schema["resources"] = _reconcile.reconcile_resources(schema)
+
+    return schema
+
+
+def resolve_root_name(schema: Dict[str, Any]) -> str:
+    """The root client class name codegen WILL emit for ``schema`` — the SINGLE
+    source of truth. ``root_name`` (or ``_camel(slug)``) is collision-suffixed
+    against the resource/enum/error names by the shared ``_ModuleNames`` allocator
+    (resources are reserved first, so a ``root_name`` equal to a resource name is
+    the one suffixed). docgen and the CLI MUST call this instead of re-deriving the
+    root, or a published import line names a class codegen never emitted (the agent
+    copying it gets ImportError)."""
+    # Normalize first so the allocation context matches render_module exactly
+    # (render_module allocates names on the normalized schema).
+    return _ModuleNames(_normalize_schema(schema)).root
+
+
+def _member_allocation(
+    operations: Dict[str, Any],
+    sub_resources: Dict[str, Any],
+    fields: Dict[str, Any],
+    *,
+    reserved: Set[str],
+) -> Tuple[Dict[str, str], Dict[str, str], Dict[str, str]]:
+    """SINGLE source of per-resource member idents, returned as
+    ``(sub_attrs, op_idents, field_idents)``.
+
+    ONE member namespace per class. Allocate in precedence order
+    (sub-resource accessor > operation method > field) so a lower-precedence
+    member colliding with a higher one is the one suffixed. Seeded with the
+    runtime-structural reserved names so e.g. a field ``_api`` becomes
+    ``_api_`` (raw it crashes construction).
+
+    Instance-op routing is one symmetric invariant: an op is an instance
+    method IFF it has a ``$self`` pin. The spec has no instance-reference
+    mechanism OTHER than ``$self``, so a pinless op cannot be instance-bound
+    by construction — it is a lookup/factory and belongs on the root
+    collection (whose emit set is the exact complement:
+    ``not _op_has_self_pin``).
+
+    Both the emitter (``_render_resource_class``) and ``op_call_descriptors``
+    call THIS function — the descriptor walk previously re-ran these loops by
+    hand ("byte-for-byte") and could drift silently.
+    """
+    member_taken: Set[str] = set()
+
+    # 1) Sub-resource accessor attrs (highest precedence).
+    sub_attrs: Dict[str, str] = {}
+    for sub_name, sub_body in sub_resources.items():
+        if not isinstance(sub_body, dict):
+            continue
+        sub_attrs[sub_name] = _allocate_ident(
+            sub_name, member_taken, fallback="sub", reserved=reserved
+        )
+
+    # 2) Operation method names — only the ops emitted on the instance (the
+    # collection-level lookups/factories must NOT consume a member slot).
+    op_idents: Dict[str, str] = {}
+    for op_name, op_body in operations.items():
+        if not isinstance(op_body, dict):
+            continue
+        if not _op_has_self_pin(op_body):
+            continue
+        op_idents[op_name] = _allocate_ident(
+            op_name, member_taken, fallback="call", reserved=reserved
+        )
+
+    # 3) Field idents (lowest precedence) — reserving the runtime names AND
+    # the already-taken sub/op members. A wire field that collides keeps its
+    # wire read via the alias the emitter records.
+    field_idents: Dict[str, str] = {}
+    for fname in fields.keys():
+        field_idents[fname] = _allocate_ident(
+            fname, member_taken, fallback="field", reserved=reserved
+        )
+    return sub_attrs, op_idents, field_idents
+
+
+def op_call_descriptors(
+    schema: Dict[str, Any], *, _norm: Optional[Dict[str, Any]] = None
+) -> Dict[str, str]:
+    """``{docgen-ref → call_expr}`` for every operation codegen emits a call path
+    for — the SINGLE source docgen reads so the README "Call" column can't
+    diverge from the emitted code. ``call_expr`` is the user-facing call shape
+    (e.g. ``client.subreddits.search()``, ``subreddit.refresh()``,
+    ``post.comments.list()``).
+
+    ``_norm`` (private) lets a caller that already normalized the schema —
+    ``render_readme`` consumes three normalized reads per API — share one
+    normalization instead of paying it per read; it must be exactly
+    ``_normalize_schema(schema)``.
+
+    A standalone READ: it does NOT touch ``render_module`` or any emitted-source
+    path, so already-generated clients and the runtime are unaffected (additive).
+
+    The walk iterates the NORMALIZED schema's resources/ops — the EMITTED op
+    set, including a ``fetched_by``-synthesized ``get`` — so every emitted
+    callable has a descriptor. Normalize only ADDS ops and never
+    removes/renames an op or resource key, so this is a superset of the raw
+    walk: every raw docgen ref still resolves (no silent ref fall-back), and
+    the README's normalized row source finds its synthesized rows too. Name
+    ALLOCATION runs against the same normalized view (``_ModuleNames`` + the
+    per-resource member/collection ident maps), matching the emitter
+    byte-for-byte. The key is EXACTLY docgen's ``ref`` format
+    (``<resource_spec_key>.<op>`` or ``<resource_spec_key>.<sub>.<op>``).
+
+    Routing branches on the single ``_op_has_self_pin`` invariant:
+      * collection (pinless) → ``client.<accessor>.<method>()`` — accessor is the
+        allocator-assigned root-collection attr (matching the emitted ``@property``,
+        suffixed on a plural collision);
+      * ``$self``-pinned → ``<instance>.<method>()`` active-record (the root
+        collection is ``pass``-bodied for these, so a ``client.<plural>.<op>``
+        call would AttributeError);
+      * sub-resource → ``<instance>.<sub_attr>.<method>()`` active-record (the
+        sub-resource accessor is a class-level ``@property``, so the class-dotted
+        ``<ResourceCls>.<sub_attr>`` form AttributeErrors at runtime).
+    """
+    norm = _norm if _norm is not None else _normalize_schema(schema)
+    norm_resources = norm.get("resources")
+    norm_resources = _as_dict(norm_resources)
+    raw_resources = schema.get("resources")
+    raw_resources = _as_dict(raw_resources)
+    names = _ModuleNames(norm)
+    out: Dict[str, str] = {}
+    reserved_member = _runtime_reserved_member_names()
+    coll_reserved = _collection_reserved()
+
+    # Signature rendering inputs — the same joins the emitter uses.
+    endpoint_input_params: Dict[str, Dict[str, Any]] = {
+        ep["name"]: (ep.get("input_params") or {})
+        for ep in norm.get("endpoints", [])
+        if isinstance(ep, dict) and isinstance(ep.get("name"), str)
+    }
+    descr_enums = norm.get("enums")
+    descr_enums = _as_dict(descr_enums)
+    descr_enum_alloc: Dict[str, str] = {_camel(ek): ev for ek, ev in names.enums.items()}
+
+    def _sig(op_body: Dict[str, Any]) -> str:
+        """The op's full emitted parameter list (no ``self``), via the same
+        ``_op_param_records`` the emitter consumes — required params as
+        ``name: type``, optionals as ``name: type = None``, then the synthetic
+        paginator kwargs (real, useful: the runtime's window-exhaustion remedy
+        is ``limit=``). NEVER raises: the descriptor map must stay TOTAL even
+        for a malformed op (the emitter is where malformed specs fail loud),
+        so any error degrades to the previous empty-paren form."""
+        try:
+            raw_takes = op_body.get("takes")
+            takes: Dict[str, Any] = dict(raw_takes) if isinstance(raw_takes, dict) else {}
+            raw_pg = op_body.get("pagination")
+            pg: Optional[Dict[str, Any]] = raw_pg if isinstance(raw_pg, dict) else None
+            paginator_param = pg.get("request_param") if pg else None
+            if paginator_param:
+                takes = {k: v for k, v in takes.items() if v != paginator_param}
+            endpoint = op_body.get("endpoint")
+            params_for_ep: Dict[str, Any] = (
+                endpoint_input_params.get(endpoint) if isinstance(endpoint, str) else None
+            ) or {}
+            records, _ = _op_param_records(takes, params_for_ep, descr_enum_alloc, descr_enums)
+            decls = [r[1] for r in records]
+            if pg and pg.get("scheme") is not None:
+                idents = {r[0] for r in records}
+                if "limit" not in idents:
+                    decls.append("limit: Optional[int] = None")
+                if "max_fetches" not in idents:
+                    decls.append("max_fetches: int = 1000")
+            return ", ".join(decls)
+        except Exception:  # noqa: BLE001 — totality over fidelity, by contract
+            return ""
+
+    for rname, raw_rspec in raw_resources.items():
+        if not isinstance(raw_rspec, dict):
+            continue
+        # Allocation context is the NORMALIZED resource (matches the emitter);
+        # the ref walk below iterates the RAW resource (matches docgen).
+        norm_rspec = norm_resources.get(rname)
+        if not isinstance(norm_rspec, dict):
+            norm_rspec = raw_rspec
+        res_cls = names.resources[rname]
+        operations = norm_rspec.get("operations")
+        operations = _as_dict(operations)
+        sub_resources = norm_rspec.get("sub_resources")
+        sub_resources = _as_dict(sub_resources)
+
+        # Shared single-source allocation — ``_member_allocation`` is the same
+        # function the emitter calls (sub-attr > instance-op > field
+        # precedence), so these idents CANNOT drift from the emitted class.
+        norm_fields = norm_rspec.get("fields")
+        norm_fields = _as_dict(norm_fields)
+        sub_attrs, instance_op_idents, _field_idents = _member_allocation(
+            operations, sub_resources, norm_fields,
+            reserved=reserved_member,
+        )
+
+        # Collection-level op idents — same single source as the renderer + gate,
+        # so a docgen "Call" cell never references a suppressed accessor.
+        coll_emit = _root_collection_emit_ops(operations)
+        coll_op_idents = _collection_op_idents(coll_emit, reserved=coll_reserved)
+        # The allocator-assigned root-collection accessor (suffixed on a plural
+        # collision) — matches the emitted ``@property``. Falls back to the raw
+        # plural only for a resource with no root collection (no ops).
+        accessor = names.root_collection_attrs.get(
+            rname, _plural_attr(res_cls, norm_rspec)
+        )
+        instance_var = _safe_ident(res_cls.lower())
+
+        for op_name, op_body in operations.items():
+            if not isinstance(op_body, dict):
+                continue
+            ref = f"{rname}.{op_name}"
+            if _op_has_self_pin(op_body):
+                method = instance_op_idents[op_name]
+                out[ref] = f"{instance_var}.{method}({_sig(op_body)})"
+            else:
+                # ``coll_op_idents`` is the renderer's emit set (pinless ops with a
+                # resolvable endpoint). A pinless op that renders no method (e.g.
+                # no `endpoint`) is absent — emit a bare, non-callable ref so the
+                # descriptor map stays TOTAL (no KeyError → no aborted sync) and
+                # never spells the suppressed ``client.<plural>`` accessor.
+                method = coll_op_idents.get(op_name)
+                out[ref] = (
+                    f"client.{accessor}.{method}({_sig(op_body)})"
+                    if method else f"{rname}.{op_name}"
+                )
+
+        # Sub-resource ops: active-record <instance>.<sub_attr>.<method>().
+        for sub_name, sub_body in sub_resources.items():
+            if not isinstance(sub_body, dict):
+                continue
+            sub_attr = sub_attrs.get(sub_name)
+            if sub_attr is None:
+                continue
+            _norm_sub_ops = sub_body.get("operations")
+            sub_ops: Dict[str, Any] = _norm_sub_ops if isinstance(_norm_sub_ops, dict) else {}
+            valid_sub_ops = [n for n, b in sub_ops.items() if isinstance(b, dict)]
+            sub_op_idents = _collection_op_idents(valid_sub_ops, reserved=coll_reserved)
+            for op_name in valid_sub_ops:
+                ref = f"{rname}.{sub_name}.{op_name}"
+                method = sub_op_idents[op_name]
+                # Active-record form on the lowercase INSTANCE var — the
+                # sub-resource accessor is a class-level ``@property`` so the
+                # class-dotted ``<ResourceCls>.<sub_attr>`` form AttributeErrors.
+                out[ref] = f"{instance_var}.{sub_attr}.{method}({_sig(sub_ops[op_name])})"
+
+    return out
+
+
+def _factory_gate(
+    res_spec: Dict[str, Any], ops: Dict[str, Any], subs: Dict[str, Any]
+) -> Optional[Tuple[str, Optional[str]]]:
+    """The constructible-factory eligibility gate — the SINGLE source shared by
+    codegen's ``_factory_rows`` pass and ``resource_surface``'s reachability
+    facts (a divergence silently changes which ``client.<plural>`` accessors
+    codegen suppresses vs. which docgen credits). Returns ``None`` when the
+    resource is not an eligible factory at all (not constructible / no
+    instance-navigable surface / no ``str`` key), else ``(keyed_by, unsafe_pin)``
+    where ``unsafe_pin`` is the offending NON-key pin that makes the factory
+    derived-unsafe (suppressed), or ``None`` for a SAFE factory."""
+    instance_ops = [n for n, b in ops.items() if isinstance(b, dict) and _op_has_self_pin(b)]
+    keyed_by = res_spec.get("keyed_by")
+    if not (res_spec.get("constructible") and (instance_ops or subs)
+            and isinstance(keyed_by, str) and keyed_by):
+        return None
+    return keyed_by, _constructible_unsafe_pin(res_spec, keyed_by)
+
+
+def _is_safe_factory(
+    res_spec: Dict[str, Any], ops: Dict[str, Any], subs: Dict[str, Any]
+) -> bool:
+    """Whether ``res_spec`` is a SAFE constructible factory (eligible AND no
+    unsafe non-key pin). Thin reachability view over :func:`_factory_gate`."""
+    gate = _factory_gate(res_spec, ops, subs)
+    return gate is not None and gate[1] is None
+
+
+def _factory_rows(
+    resources: Dict[str, Any],
+    names: "_ModuleNames",
+    *,
+    reserved_root_attrs: Set[str],
+    emitted_root_attrs: Set[str],
+) -> Tuple[List[Tuple[str, str, str, str]], List[Tuple[str, str, str]]]:
+    """Constructible-factory rows + suppression records — the SINGLE source
+    for the emitter's factory pass, the README's factory rows, and the CLI's
+    suppression warnings. The factory-attr allocation is order-dependent on
+    ``emitted_root_attrs`` (suffixing on clashes), which this function MUTATES
+    exactly as the emitter's inline pass did — a standalone re-derivation of
+    these gates is the drift class the descriptor machinery exists to prevent.
+
+    Returns ``(rows, suppressed)``: ``rows`` are
+    ``(factory_attr, ResourceClass, key_ident, key_anno)`` in resource order;
+    ``suppressed`` are ``(res_name, unsafe_field, keyed_by)`` for factories
+    the derived-safety gate refused.
+    """
+    rows: List[Tuple[str, str, str, str]] = []
+    suppressed: List[Tuple[str, str, str]] = []
+    for res_name, res_spec in resources.items():
+        if not isinstance(res_spec, dict):
+            continue
+        # Emit a factory only when the resource is an eligible, derived-SAFE
+        # constructible: an INSTANCE-navigable surface (a `$self`-pinned op or a
+        # sub-resource — a pinless-only constructible routes ops to the root
+        # collection, so a bare `resource(key)` handle would be dead) AND a str
+        # key AND no NON-key pin (don't trust the agent's flag — a handle whose
+        # ops silently send None on a non-key pin is suppressed; the resource is
+        # still reachable via its collection/search results). _factory_gate is
+        # the single source the reachability facts also consume.
+        ops = _as_dict(res_spec.get("operations"))
+        subs = _as_dict(res_spec.get("sub_resources"))
+        gate = _factory_gate(res_spec, ops, subs)
+        if gate is None:
+            continue
+        keyed_by, unsafe_pin = gate
+        if unsafe_pin is not None:
+            suppressed.append((res_name, unsafe_pin, keyed_by))
+            continue
+        res_cls = names.resources[res_name]
+        # This resource's emitted collection accessor (allocator-suffixed on a
+        # plural collision) — falls back to the raw plural for resources without
+        # a root collection (no ops → not in the allocated map).
+        plural_attr = names.root_collection_attrs.get(
+            res_name, _plural_attr(res_cls, res_spec)
+        )
+        factory_attr = _safe_ident(res_cls.lower())
+        # Skip when the factory name would collide with THIS resource's own
+        # plural collection attr — the collection wins.
+        if factory_attr == plural_attr and plural_attr in emitted_root_attrs:
+            continue
+        # Otherwise suffix on any reserved / already-emitted clash.
+        while factory_attr in reserved_root_attrs or factory_attr in emitted_root_attrs:
+            factory_attr = f"{factory_attr}_"
+        key_ident = _safe_ident(keyed_by)
+        key_anno = _factory_key_annotation(res_spec, keyed_by)
+        rows.append((factory_attr, res_cls, key_ident, key_anno))
+        emitted_root_attrs.add(factory_attr)
+    return rows, suppressed
+
+
+def factory_descriptors(
+    schema: Dict[str, Any], *, _norm: Optional[Dict[str, Any]] = None
+) -> Dict[str, list]:
+    """Standalone read of the constructible-factory surface for the docs layer
+    — the same ``_factory_rows`` the emitter consumes, computed over the
+    normalized schema with the same pre-factory accumulator state (the
+    collection accessors), so a documented factory row CANNOT drift from the
+    emitted one. Additive: touches no emitted-source path. ``_norm`` (private)
+    shares a caller's existing ``_normalize_schema(schema)`` result.
+
+    Returns ``{"rows": [(factory_attr, ResourceClass, key_ident, key_anno)],
+    "suppressed": [(res_name, unsafe_field, keyed_by)]}`` in emission order.
+    """
+    norm = _norm if _norm is not None else _normalize_schema(schema)
+    resources = norm.get("resources")
+    if not isinstance(resources, dict) or not resources:
+        return {"rows": [], "suppressed": []}
+    names = _ModuleNames(norm)
+    from parse_sdk._runtime import BaseAPI as _BaseAPI
+    reserved_root_attrs: Set[str] = set(dir(_BaseAPI)) | {"get", "list", "search"}
+    # Reproduce the emitter's pre-factory accumulator: every root-collection
+    # accessor is emitted before any factory (same gate as the emit loop).
+    emitted_root_attrs: Set[str] = {
+        names.root_collection_attrs[res_name]
+        for res_name, res_spec in resources.items()
+        if isinstance(res_spec, dict)
+        and _root_collection_emit_ops(res_spec.get("operations"))
+    }
+    rows, suppressed = _factory_rows(
+        resources, names,
+        reserved_root_attrs=reserved_root_attrs,
+        emitted_root_attrs=emitted_root_attrs,
+    )
+    return {"rows": rows, "suppressed": suppressed}
+
+
+def render_module(schema: Dict[str, Any], *, base_url: str) -> Optional[str]:
+    """Render the full ``__init__.py`` for a single API. Returns None if
+    the schema can't be modeled (no ``resources`` block — hard cutover)."""
+    resources = schema.get("resources")
+    if not isinstance(resources, dict) or not resources:
+        return None
+
+    # Normalize cross-SDK before render — see _normalize_schema for the rules.
+    schema = _normalize_schema(schema)
+    resources = schema["resources"]
+
+    # The id becomes ``SCRAPER_ID`` — a URL path segment of every request the
+    # generated client makes. Gate it before any rendering (early authoring
+    # signal; the runtime sink percent-encodes regardless).
+    _require_wire_segment(schema.get("id"), "scraper id")
+
+    # Fail closed on a missing/non-string slug (it becomes the package/module/path
+    # name). A raw KeyError/TypeError here would escape render_preview (which only
+    # catches CodegenError) and abort the whole `parse sync` for every API.
+    slug = schema.get("slug")
+    if not isinstance(slug, str) or not slug:
+        raise CodegenError(f"schema slug {slug!r} is missing or not a non-empty string")
+
+    # Module-level name allocator (P0.2): reserves ONE namespace across
+    # root + resources + enums + errors + collections, suffix-on-collision. Every
+    # class def, registry key, enum-binding ref, accessor, and the resolvability
+    # gate's name sets derive from its allocated VALUES.
+    names = _ModuleNames(schema)
+    root_name = names.root
+
+    # ``_camel(enum spec key) → allocated enum class name``. Enum bindings on
+    # fields/params reference an enum by name; resolve them to the allocated
+    # class (a collision suffix can move it). Keyed on the
+    # canonical ``_camel`` form so a differently-spelled binding still matches.
+    enum_alloc: Dict[str, str] = {
+        _camel(ek): ev for ek, ev in names.enums.items()
+    }
+
+    # SINGLE SOURCE OF TRUTH for return types: rewrite each top-level resource
+    # op's ``returns`` to the ALLOCATED owning-resource class name, BEFORE any
+    # rendering. The emitted annotation, the _coerce label, and the
+    # _RESOURCE_CLASSES key all read this rewritten value, so they cannot diverge.
+    # Identity-keyed (per owning resource), so it is unambiguous under _camel
+    # collisions. Copy-on-write: the caller's schema dict is left untouched.
+    rewritten_resources: Dict[str, Any] = {}
+    for _rk, _rspec in resources.items():
+        if not (isinstance(_rspec, dict) and isinstance(_rspec.get("operations"), dict)):
+            rewritten_resources[_rk] = _rspec
+            continue
+        _owning_alloc = names.resources[_rk]
+        _owning_camel = _camel(_rk)
+        _new_ops: Dict[str, Any] = {}
+        for _op_name, _op in _rspec["operations"].items():
+            if isinstance(_op, dict) and "returns" in _op:
+                _new_ops[_op_name] = {
+                    **_op,
+                    "returns": _allocate_returns(_op["returns"], _owning_alloc, _owning_camel),
+                }
+            else:
+                _new_ops[_op_name] = _op
+        rewritten_resources[_rk] = {**_rspec, "operations": _new_ops}
+    # Self-contained copy-on-write: rebind ``schema`` to a NEW dict rather than
+    # mutating ``schema["resources"]`` in place, so the no-caller-mutation
+    # invariant holds LOCALLY and does not silently depend on _normalize_schema's
+    # leading shallow-copy staying first.
+    schema = {**schema, "resources": rewritten_resources}
+    resources = rewritten_resources
+
+    # Build the {endpoint_name: input_params} lookup that types each
+    # operation's kwargs. Key is ``endpoints`` (the SDKSchema shape from the
+    # executor's _row_to_schema) — NOT ``apis``. An op's kwarg is typed by
+    # joining its ``takes`` VALUE (endpoint param name) against this map.
+    endpoint_input_params: Dict[str, Dict[str, Any]] = {
+        ep["name"]: (ep.get("input_params") or {})
+        for ep in schema.get("endpoints", [])
+        if isinstance(ep, dict) and isinstance(ep.get("name"), str)
+    }
+
+    # {endpoint_name: HTTP method}. The real verb lives on the normalized
+    # ``endpoints[].method`` (the executor's SDKEndpoint.method). An op's
+    # request uses this rather than a hardcoded GET. A missing entry defaults
+    # to POST — matching the executor schema projector's default — so the
+    # emitted verb tracks the real endpoint method.
+    endpoint_methods: Dict[str, str] = {
+        ep["name"]: str(ep.get("method") or "POST").upper()
+        for ep in schema.get("endpoints", [])
+        if isinstance(ep, dict) and isinstance(ep.get("name"), str)
+    }
+
+    # {endpoint_name: description}. An operation's narrative is the description
+    # of the endpoint it calls — resolved at render time by ``op["endpoint"]``,
+    # the same inline join docgen uses (D5: one rule, one mechanism, no stamp).
+    endpoint_descriptions: Dict[str, str] = endpoint_description_map(schema)
+
+    # {endpoint_name: return_schema}. The captured response sample lives here
+    # The empty-results discriminator (emitted arm B) reads the
+    # unwrapped sample's top-level key-set per op (``_sample_keys_for``) to tell
+    # a legit zero-result from a mis-derived ``items_path``. Same ``endpoints``
+    # source + defensive-resolution pattern as ``endpoint_input_params``.
+    endpoint_return_schemas: Dict[str, Any] = {
+        ep["name"]: ep.get("return_schema")
+        for ep in schema.get("endpoints", [])
+        if isinstance(ep, dict) and isinstance(ep.get("name"), str)
+    }
+
+    # {ALLOCATED element resource name -> its declared ``keyed_by`` (or None when
+    # keyless)}. The identity-dedup arm needs the element resource's
+    # ``keyed_by`` at BOTH the resource-op site and the collection site — but a
+    # collection method only has the element LABEL (``_collection_element(returns)``)
+    # in scope, not the element resource's spec. This map supplies it. Keyed on
+    # the ALLOCATED class name because ``returns`` were rewritten to allocated
+    # names above, so ``_collection_element`` yields the allocated label. The
+    # value is the RAW declared ``keyed_by`` (matching the Step-0 census's
+    # ``_keyed_by_for``); a container/absent key still emits no dedup because the
+    # sample-uniqueness gate (``_dedup_eligible``) fails on it, and even if it
+    # didn't the runtime ``_KEY_FIELD`` would be None and identity-dedup would
+    # no-op (``_identity_key`` → None → never deduped → no data loss).
+    element_keyed_by: Dict[str, Optional[str]] = {}
+    for _rk, _rspec in resources.items():
+        if not isinstance(_rspec, dict):
+            continue
+        _kb = _rspec.get("keyed_by")
+        element_keyed_by[names.resources[_rk]] = _kb if isinstance(_kb, str) and _kb else None
+
+    # Read the engine version lazily to avoid an import cycle — codegen_v2 is
+    # imported by cli, and parse_sdk/__init__ imports only _runtime, so
+    # importing parse_sdk here is safe.
+    from parse_sdk import __version__ as _engine_version
+
+    parts: List[str] = []
+    parts.append(_HEADER.format(
+        base_url=_escape_header_field(base_url),
+        api_name=_escape_header_field(schema.get("name", slug)),
+        slug=_escape_header_field(slug),
+        scraper_id=_escape_header_field(schema["id"]),
+        timestamp=datetime.now(timezone.utc).isoformat(),
+        engine_version=_engine_version,
+    ))
+
+    # Stamp the engine version the client was built against so a runtime/build
+    # version skew is detectable (prisma's silent-corruption mode).
+    parts.append(f'__generated_with__ = "{_engine_version}"\n\n')
+
+    # Module-level coerce helper that knows about the resource registry.
+    parts.append("from parse_sdk._runtime import coerce as _runtime_coerce\n\n")
+    parts.append("def _coerce(value, type_label, ctx, mode='element'):\n")
+    parts.append("    # `ctx` is the calling object (resource instance or collection).\n")
+    parts.append("    # `mode` (S5) selects the return boundary: a single-resource return\n")
+    parts.append("    # emits mode='return' (strict husk/scalar fail-loud); per-element\n")
+    parts.append("    # paginator rows emit mode='element' (lenient degrade-to-raw, the\n")
+    parts.append("    # default). The strict verdict needs the return contract boundary,\n")
+    parts.append("    # so boundary is True exactly when mode=='return'.\n")
+    parts.append("    api = getattr(ctx, '_api', None) or (ctx if isinstance(ctx, _BaseAPI) else None)\n")
+    parts.append("    parent = ctx if not isinstance(ctx, _BaseAPI) else None\n")
+    parts.append("    return _runtime_coerce(value, type_label, resource_classes=_RESOURCE_CLASSES,\n")
+    parts.append("                           api=api, parent=parent, boundary=(mode == 'return'), mode=mode)\n\n\n")
+
+    # Empty-results extraction helper — imported ONLY when the module has at
+    # least one paginated op (the sole reference site is a ``_fetch_page`` body).
+    # A non-paginated-only module stays byte-identical (no unused import), so the
+    # the emitted byte-delta stays confined to the paginated-op population.
+    if _schema_has_paginated_op(resources):
+        parts.append("from parse_sdk._runtime import _extract_items\n\n\n")
+
+    # Dotted-pagination-path resolver — imported ONLY when some paginated op
+    # declares a dotted response path (the sole reference sites are dotted
+    # ``_walk(_resp, ...)`` emits inside a ``_fetch_page`` body). A flat-path-only
+    # module stays byte-identical (no unused import); the frozen corpus has zero
+    # dotted paths, so this import is absent corpus-wide.
+    if _schema_has_dotted_pagination_path(resources):
+        parts.append("from parse_sdk._runtime import _walk\n\n\n")
+
+    # Enums — emit under their ALLOCATED names (P0.2).
+    enums = schema.get("enums")
+    enums = _as_dict(enums)
+    for enum_name, enum_spec in enums.items():
+        if not isinstance(enum_spec, dict):
+            continue
+        parts.append(_render_enum(names.enums[enum_name], enum_spec))
+        parts.append("\n\n\n")
+
+    # Errors — emit under their ALLOCATED names (P0.2). Also collect the
+    # ``(wire_kind, AllocatedClassName)`` map for every error declaring a
+    # ``code`` — emitted as ``_ERROR_CLASSES`` on the root client so the runtime
+    # raises the domain class for a matching wire ``kind``. Authoring-time the
+    # gate enforces ``code`` ∈ the closed kind set AND uniqueness-per-API, so
+    # this map is unambiguous by construction; we keep the FIRST occurrence if a
+    # malformed (un-gated) spec ever repeats a code, so codegen never crashes.
+    errors = schema.get("errors")
+    errors = _as_dict(errors)
+    error_code_classes: List[Tuple[str, str]] = []
+    _seen_codes: Set[str] = set()
+    # Schema-wide union of endpoint input-param names — the source set for
+    # carry hydration (_CARRY_PARAMS); see _render_error's docstring.
+    input_param_union: Set[str] = {
+        p for ep_params in endpoint_input_params.values() for p in ep_params
+    }
+    for err_name, err_spec in errors.items():
+        if not isinstance(err_spec, dict):
+            continue
+        parts.append(_render_error(names.errors[err_name], err_spec, input_param_union))
+        parts.append("\n\n")
+        code = err_spec.get("code")
+        if isinstance(code, str) and code and code not in _seen_codes:
+            _seen_codes.add(code)
+            error_code_classes.append((code, names.errors[err_name]))
+
+    # Full emitted name sets — the field-annotation resolvability gate validates
+    # every field annotation against these. Derived from the allocator's VALUES
+    # (not a fresh ``{_camel(rn)}`` comprehension) so a suffixed resource/enum
+    # doesn't silently degrade a referencing field to ``Any``.
+    emitted_resource_names: Set[str] = names.resource_values()
+    emitted_enum_names: Set[str] = names.enum_values()
+
+    # Field-type labels per emitted resource — so an op whose ``returns`` is a
+    # NON-collection ENVELOPE resource but which paginates via ``items_path`` into
+    # one of its ``List[X]`` fields coerces rows to the ELEMENT ``X``, not the
+    # envelope husk. Keyed by allocated resource name; labels via the same
+    # ``_coerce_type_label`` path as the emitted field annotations (enum-bound
+    # fields excluded — never a resource list).
+    #
+    # KNOWN LIMITATION (PR #43 review): the stored labels are ``_coerce_type_label``
+    # output, so an inner element token is the spec-camel name (``Paper``) — NOT a
+    # collision-suffixed allocated name. This is consistent with the pre-existing
+    # ``_collection_element(returns)`` path for direct ``List[X]`` returns
+    # (``_allocate_returns`` rewrites only the owning resource, not cross-resource
+    # refs), so a resource-name collision could emit a ``_coerce`` label that misses
+    # its ``_RESOURCE_CLASSES`` key. Zero corpus cases today; a uniform cross-resource
+    # element allocation (here AND on the direct-return path) is a tracked follow-up.
+    resource_field_labels: Dict[str, Dict[str, str]] = {}
+    for _rn, _rspec in resources.items():
+        if not isinstance(_rspec, dict):
+            continue
+        _flabels: Dict[str, str] = {}
+        for _fn, _fv in _as_dict(_rspec.get("fields")).items():
+            _tlabel, _ebind, _ = _extract_field_spec(_fv)
+            if not _ebind:
+                _flabels[_fn] = _coerce_type_label(_tlabel)
+        resource_field_labels[names.resources[_rn]] = _flabels
+
+    # Resource classes (and their sub-resource collections)
+    for res_name, res_spec in resources.items():
+        if not isinstance(res_spec, dict):
+            continue
+        parts.append(_render_resource_class(
+            names.resources[res_name], res_spec,
+            res_key=res_name,
+            names=names,
+            enum_alloc=enum_alloc,
+            enums=enums,
+            endpoint_input_params=endpoint_input_params,
+            endpoint_methods=endpoint_methods,
+            endpoint_descriptions=endpoint_descriptions,
+            endpoint_return_schemas=endpoint_return_schemas,
+            element_keyed_by=element_keyed_by,
+            resource_names=emitted_resource_names,
+            enum_names=emitted_enum_names,
+            resource_field_labels=resource_field_labels,
+        ))
+        parts.append("\n\n")
+        # Sub-resource collections — emit AFTER the resource class but they
+        # need to be importable before the property uses them. Forward refs
+        # in the property annotation make this work.
+        for sub_name, sub_spec in (res_spec.get("sub_resources") or {}).items():
+            if isinstance(sub_spec, dict):
+                sub_ops = sub_spec.get("operations")
+                sub_ops = _as_dict(sub_ops)
+                parts.append(_render_collection(
+                    names.sub_collections[(res_name, sub_name)],
+                    [n for n, b in sub_ops.items() if isinstance(b, dict)],
+                    sub_ops,
+                    endpoint_input_params=endpoint_input_params,
+                    endpoint_methods=endpoint_methods,
+                    endpoint_descriptions=endpoint_descriptions,
+                    endpoint_return_schemas=endpoint_return_schemas,
+                    element_keyed_by=element_keyed_by,
+                    enum_alloc=enum_alloc,
+                    enums=enums,
+                    resource_field_labels=resource_field_labels,
+                ))
+                parts.append("\n\n")
+
+    # Root collections (one per top-level resource that has operations)
+    root_collections: List[Tuple[str, str]] = []
+    # Root factories — no-network accessors for constructible resources
+    # (``reddit.subreddit("x")``). Built in the same loop so collision
+    # resolution can see the collection attrs (emitted first).
+    root_factories: List[Tuple[str, str, str, str]] = []
+    # Reserved names a factory attr must not shadow: BaseAPI's members plus
+    # a few collection-verb words, plus every root attr already emitted
+    # (collections precede factories). Built from dir(BaseAPI), not a
+    # hand-literal, so it tracks the runtime base.
+    from parse_sdk._runtime import BaseAPI as _BaseAPI
+    reserved_root_attrs: Set[str] = set(dir(_BaseAPI)) | {"get", "list", "search"}
+    emitted_root_attrs: Set[str] = set()
+    for res_name, res_spec in resources.items():
+        if not isinstance(res_spec, dict):
+            continue
+        # Same gate as the allocator (codegen_v2 `_ModuleNames`): a resource with
+        # no real root-collection method gets no collection. MUST match the
+        # allocator's condition exactly — the lines below direct-index
+        # `names.root_collections[res_name]`, so a one-sided change would KeyError.
+        if not _root_collection_emit_ops(res_spec.get("operations")):
+            continue
+        res_ops = res_spec.get("operations")
+        res_ops = _as_dict(res_ops)
+        attr = names.root_collection_attrs[res_name]
+        coll_cls = names.root_collections[res_name]
+        parts.append(_render_collection(
+            coll_cls,
+            _root_collection_emit_ops(res_ops),
+            res_ops,
+            endpoint_input_params=endpoint_input_params,
+            endpoint_methods=endpoint_methods,
+            endpoint_descriptions=endpoint_descriptions,
+            endpoint_return_schemas=endpoint_return_schemas,
+            element_keyed_by=element_keyed_by,
+            enum_alloc=enum_alloc,
+            enums=enums,
+            resource_field_labels=resource_field_labels,
+        ))
+        parts.append("\n\n")
+        root_collections.append((attr, coll_cls))
+        emitted_root_attrs.add(attr)
+
+    # Factory pass — runs AFTER all collection attrs are recorded so the
+    # collision check sees the full set. Gates + suffix allocation live in
+    # `_factory_rows` (shared with the docs-layer `factory_descriptors` read,
+    # so the documented surface cannot drift from the emitted one).
+    factory_rows, factory_suppressed = _factory_rows(
+        resources, names,
+        reserved_root_attrs=reserved_root_attrs,
+        emitted_root_attrs=emitted_root_attrs,
+    )
+    for _sup_name, _sup_unsafe, _sup_key in factory_suppressed:
+        logger.warning(
+            "constructible factory for %r suppressed: a reachable op pins "
+            "non-key field %r (keyed_by=%r) — hand-built instance unsafe",
+            _sup_name, _sup_unsafe, _sup_key,
+        )
+    root_factories.extend(factory_rows)
+
+    # Resource registry — for the runtime string-label coerce router. Keyed by
+    # the ALLOCATED class name, which is exactly the label the rewritten
+    # ``returns`` / `_coerce` sites emit. Allocated names are unique by
+    # construction (_ModuleNames._alloc suffixes on collision), so each key maps
+    # 1:1 to its class — no dedup required.
+    parts.append("# Resource registry — populated below so each Resource class can resolve\n")
+    parts.append("# nested types during _from_payload coercion.\n")
+    parts.append("_RESOURCE_CLASSES: Dict[str, type] = {\n")
+    for res_name in resources:
+        if not isinstance(resources[res_name], dict):
+            continue
+        cls = names.resources[res_name]
+        parts.append(f"    {cls!r}: {cls},\n")
+    parts.append("}\n\n")
+    parts.append("for _cls in _RESOURCE_CLASSES.values():\n")
+    parts.append("    _cls._RESOURCE_REGISTRY = _RESOURCE_CLASSES\n\n\n")
+
+    # Root client
+    parts.append(_render_root_client(
+        root_name, schema, root_collections, root_factories,
+        error_classes=error_code_classes,
+    ))
+    parts.append("\n")
+
+    # __all__ for clean imports — built from the allocator (dup-free by
+    # construction: root + resources + enums + errors all in one namespace).
+    exports = names.all_exports()
+    parts.append("\n__all__ = [\n")
+    for e in exports:
+        parts.append(f"    {e!r},\n")
+    parts.append("]\n")
+
+    return "".join(parts)