parse-sdk 0.1.0__py3-none-any.whl

parse_sdk/_sync.py

@@ -0,0 +1,887 @@
+"""Sync engine — staging, gating, and atomic promotion of the generated tree.
+
+Owns stage/check/swap for ``parse sync``: build the COMPLETE next package
+beside the live one, self-test it, then promote with an atomic directory
+swap. The CLI layer (``parse_sdk.cli``) keeps fetch/render/guard/install and
+calls :func:`stage_check_swap` with rendered artifacts + resolved paths.
+User-facing output stays ``click.echo`` (CLI-layer output, hosted here
+mechanically — the extraction moved code, not behavior).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import secrets
+import shutil
+import sys
+import tempfile
+import time
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+import click
+
+from parse_sdk import __version__, checks, docgen, scaffold
+from parse_sdk._sanitize import CONTROL_BYTES as _CONSOLE_UNSAFE
+from parse_sdk.codegen_v2 import resolve_root_name
+from parse_sdk.scaffold import is_reserved_slug, safe_slug
+
+MANIFEST_NAME = "_manifest.json"
+
+# C0 controls (minus \n and \t) + DEL + the C1 controls (\x80-\x9f, which
+# include the single-byte CSI \x9b some terminals honor as an escape
+# introducer). ``click.echo`` strips ANSI only when the stream is not a TTY,
+# and a bare ``\r`` survives even piped — so a server-controlled string
+# (slug/name/endpoint/error text) could rewrite or hide earlier terminal
+# output. Server strings pass through ``_safe_console`` before any echo;
+# locally-derived values (assigned slugs, paths) don't need it. None of the
+# stripped codepoints has a legitimate role in a slug/name/endpoint. The class
+# is single-sourced in ``parse_sdk._sanitize`` (imported as ``_CONSOLE_UNSAFE``),
+# shared with ``_runtime``'s excerpt sanitizer so the two cannot drift.
+
+
+def _safe_console(s: object) -> str:
+    """Strip terminal-control characters from a server-supplied string."""
+    return _CONSOLE_UNSAFE.sub("", str(s))
+
+
+def _load_manifest(target_root: Path) -> dict:
+    """Read parse_apis/_manifest.json ({uuid: slug}); {} if absent/malformed.
+
+    The malformed→{} contract holds PER ENTRY too: a non-string key or slug
+    (hand-edited / corrupted manifest) would otherwise flow into
+    ``safe_slug``/path joins and crash sync with a raw TypeError."""
+    p = target_root / MANIFEST_NAME
+    if not p.exists():
+        return {}
+    try:
+        data = json.loads(p.read_text())
+    except (json.JSONDecodeError, OSError):
+        return {}
+    if not isinstance(data, dict):
+        return {}
+    return {k: v for k, v in data.items() if isinstance(k, str) and isinstance(v, str)}
+
+
+def _assign_slugs(schemas: List[dict], prior: dict) -> dict:
+    """Return {uuid: assigned_slug} for the schemas to generate.
+
+    Pin by UUID: a uuid seen in the prior manifest keeps its slug (if that
+    slug is still usable this run), neutralizing the server's updated_at-ordered
+    flip. A candidate that collides with an already-claimed slug, or that takes
+    a package-reserved name, gets a deterministic `_<uuid8>` suffix (never
+    order-based `_2`). The one-time first-seen bare-vs-suffixed choice follows
+    the server's response order; stable thereafter.
+
+    A slug is usable only if it is (a) not reserved (``scaffold.is_reserved_slug``
+    — a name that as a directory under ``src/parse_apis/`` would shadow a
+    package-level scaffold/generated member) and (b) not already claimed by a
+    different uuid *case-insensitively* (two slugs differing only in
+    case must not collapse into one directory on a case-insensitive filesystem
+    like macOS/APFS). Both rules apply to the prior-manifest pin too (audit
+    B2-residual), so a reserved/colliding name can never be reintroduced via the
+    pin path.
+    """
+    claimed_fold: dict = {}   # casefolded slug -> uuid (this run)
+    assigned: dict = {}       # uuid -> slug
+
+    def _usable(slug: str, uuid: str) -> bool:
+        if is_reserved_slug(slug):
+            return False
+        owner = claimed_fold.get(slug.casefold())
+        return owner is None or owner == uuid
+
+    for s in schemas:
+        uuid = s["id"]
+        # Sanitize first: a server slug is used as a directory name AND an import
+        # path, so a hostile value must be made identifier-safe before it can
+        # reach any filesystem op (audit SEC-1). Prior pins are sanitized too, so
+        # an unsafe name written by an older engine is never honored verbatim.
+        candidate = safe_slug(s["slug"])
+        prior_slug = prior.get(uuid)
+        if prior_slug is not None:
+            prior_slug = safe_slug(prior_slug)
+        if prior_slug and _usable(prior_slug, uuid):
+            slug = prior_slug
+        elif _usable(candidate, uuid):
+            slug = candidate
+        else:
+            # SEC-1: the uuid suffix becomes part of a directory name AND import
+            # path, so it must be sanitized exactly like the slug — a hostile
+            # server `id` (e.g. "../../x") must not reintroduce the path
+            # separators that `safe_slug(s["slug"])` already stripped from the
+            # candidate.
+            uuid_suffix = safe_slug(uuid)[:8]
+            slug = f"{candidate}_{uuid_suffix}"
+            n = 1
+            while not _usable(slug, uuid):
+                slug = f"{candidate}_{uuid_suffix}_{n}"
+                n += 1
+        claimed_fold[slug.casefold()] = uuid
+        assigned[uuid] = slug
+    return assigned
+
+
+def _carry_skipped(prior: dict, server_uuids: set, assigned: dict) -> dict:
+    """Pins to carry into the new manifest for scrapers still in the server
+    response but SKIPPED this sync (un-modeled → not in `assigned`). Keep a pin
+    only if its slug doesn't collide with a rendered uuid's slug (rendered
+    wins; the skipped one re-derives next sync). This preserves the dir↔uuid
+    mapping across a transient un-modeling, so re-modeling doesn't flip a
+    shared-base slug — and guarantees no two uuids ever map to one slug.
+
+    Carried pins are ``safe_slug``-sanitized exactly like ``_assign_slugs``'
+    pin path: carried values flow into ``copytree``/``rmtree`` target paths, so
+    an unsafe name written by an older engine must be unrepresentable here too
+    — not merely unreachable given the current writer. (A sanitized pin that no
+    longer matches its on-disk dir simply isn't copied; the slug re-derives on
+    the next modeled sync.)
+    """
+    assigned_slugs = set(assigned.values())
+    return {
+        u: safe_slug(prior[u])
+        for u in prior
+        if u in server_uuids and u not in assigned
+        and safe_slug(prior[u]) not in assigned_slugs
+    }
+
+
+# Schema-shape accessors — total over malformed nested shapes (a hostile/buggy
+# server can deliver a non-dict ``resources`` or a non-list ``endpoints``;
+# ``_valid_schema_row`` gates only id/slug). Single-sourced here and re-exported
+# through ``cli`` so the ``parse list`` view and the sync success line never
+# drift in how they read a schema's resources/endpoints.
+def _schema_resources(schema: dict) -> dict:
+    resources = schema.get("resources")
+    return resources if isinstance(resources, dict) else {}
+
+
+def _schema_modeled(schema: dict) -> bool:
+    return bool(_schema_resources(schema))
+
+
+def _schema_endpoint_names(schema: dict) -> List[str]:
+    endpoints = schema.get("endpoints")
+    if not isinstance(endpoints, list):
+        return []
+    names: List[str] = []
+    for endpoint in endpoints:
+        if not isinstance(endpoint, dict):
+            continue
+        name = endpoint.get("name")
+        if isinstance(name, str):
+            names.append(name)
+    return names
+
+
+def _schema_resource_names(schema: dict) -> List[str]:
+    return sorted(str(name) for name in _schema_resources(schema).keys())
+
+
+def _sweep_stale_stages(src_parent: Path) -> None:
+    """Best-effort removal of staging dirs left by CRASHED runs (>1 day old).
+    Never matches a concurrent run's fresh stage (per-run unique names), and
+    deliberately leaves ``.parse_apis.old-*`` alone — after a failed restore
+    that dir can hold the user's only live copy."""
+    for stale in src_parent.glob(".parse_apis.next-*"):
+        try:
+            if time.time() - stale.stat().st_mtime > 86400:
+                shutil.rmtree(stale, ignore_errors=True)
+        except OSError:
+            pass
+
+
+def _atomic_write_text(path: Path, text: str) -> None:
+    """Write ``text`` to ``path`` atomically: a fresh temp file in the same
+    directory + ``os.replace``, so an interrupted write (Ctrl-C, OOM, shutdown)
+    can't leave a half-written, unparseable file — important for the project's
+    critical build config."""
+    fd, tmp = tempfile.mkstemp(dir=str(path.parent), prefix=f".{path.name}.", suffix=".tmp")
+    try:
+        os.write(fd, text.encode("utf-8"))
+        os.close(fd)
+        os.replace(tmp, path)
+    except BaseException:
+        try:
+            os.close(fd)
+        except OSError:
+            pass
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def _staged_check_failures(staging: Path, *, recursive: bool = True) -> List[str]:
+    """Run the staged-artifact self-tests; return human-readable failure lines
+    (empty == clean). Promotion is gated on this being empty.
+
+    ``recursive=False`` scans only the entries directly in ``staging`` (the
+    top-level artifacts), used by the whole-tree pre-promotion pass: every slug
+    dir was already gated individually in the per-slug quarantine loop, so the
+    whole-tree pass need only check the non-slug artifacts written after it."""
+    lines: List[str] = []
+    # ONE pass over the staged tree: read each file once, parse each .py once,
+    # run all four checks off the cached text/AST (checks.scan_tree). The syntax
+    # gate (compile of every __init__.py) is part of that pass — a SyntaxError
+    # the import gate's ast.parse silently skips would otherwise promote a
+    # broken/injected `__init__.py` into the live tree (see codegen header
+    # escaping, SEC). Format the four finding lists in the same order the old
+    # sequential gates produced (syntax, secrets, imports, docs).
+    found = checks.scan_tree(staging, recursive=recursive)
+    for path, err in found.syntax_errors:
+        lines.append(f"generated module {path.relative_to(staging)} is not valid Python: {err}")
+    for path, family, lineno, masked in found.secrets:
+        lines.append(
+            f"secret-shape [{family}] in {path.relative_to(staging)}:{lineno} "
+            f"({masked})")
+    for path, mod in found.forbidden_imports:
+        lines.append(f"forbidden import `{mod}` in {path.relative_to(staging)}")
+    for path, needle in found.stale_docs:
+        lines.append(f"stale import-model doc '{needle}' in {path.relative_to(staging)}")
+    return lines
+
+
+def _example_drop_reason(example_src: str) -> Optional[str]:
+    """Why a stored example must not ship — ``None`` when it is clean.
+
+    Stored examples are arbitrary user code migrated best-effort; one with a
+    stale/aliased ``parse_sdk.<slug>`` import or a leaked credential must drop
+    just that example file — never abort the whole sync for every other API.
+    Returns the FIRST failing check as a short cause string (secret-shaped
+    value / forbidden import / stale import-model doc) so the drop warning can
+    name what actually failed instead of hedging all three causes at once.
+    """
+    with tempfile.TemporaryDirectory(prefix="parse_ex_") as td:
+        d = Path(td)
+        (d / "example.py").write_text(example_src)
+        # ONE pass over the single example file (the same single-source scanner
+        # the staged-tree gate uses), then report the FIRST failing check in the
+        # secret → import → doc priority the old sequential calls produced. The
+        # syntax finding is intentionally not a drop cause for stored examples.
+        found = checks.scan_tree(d)
+        if found.secrets:
+            _, family, lineno, masked = found.secrets[0]
+            return (f"it contains a secret-shaped value [{family}] "
+                    f"at line {lineno} ({masked})")
+        if found.forbidden_imports:
+            _, mod = found.forbidden_imports[0]
+            return f"it has a forbidden import '{mod}'"
+        if found.stale_docs:
+            _, needle = found.stale_docs[0]
+            return f"it teaches a stale import model ('{needle}')"
+        return None
+
+
+# Per-slug files sync OWNS (writes every sync, compares for change-detection).
+# Non-owned residue (__pycache__, user files) is neither written nor compared.
+OWNED_SLUG_FILES = frozenset({"__init__.py", "example.py", "README.md"})
+
+# The volatile render-stamp line in a generated module's header — re-rendered
+# with a fresh wall-clock on EVERY sync, so it must be excluded from the
+# changed/unchanged comparison or every kept slug reads [changed] forever and
+# the warning gating that keys on `unchanged` never fires.
+_VOLATILE_HEADER_RE = re.compile(r"^Generated at: .*$", re.MULTILINE)
+
+# The scaffold's engine pin. Name-boundary anchored (a foreign dep named
+# `acme-parse-sdk` must not match) and whitespace-tolerant around `==`
+# (PEP 508 allows it). Always located via ``_find_pin`` — never a bare
+# ``search`` — so a TOML comment mentioning the pin can neither be restamped
+# nor satisfy the pin-presence check. Shared by the post-swap restamp and
+# `--check`'s missing-pin finding.
+_PIN_RE = re.compile(r"(?<![A-Za-z0-9._-])parse-sdk\s*==\s*([0-9A-Za-z.+!\-]+)")
+
+
+def _find_pin(text: str) -> "Optional[re.Match[str]]":
+    """The first ``parse-sdk==X`` match on a NON-comment line, or ``None``.
+
+    The resolver never reads comments, so a ``# parse-sdk==0.2.0`` line is
+    neither a pin to restamp (rewriting it would leave the real dep stale
+    while the advisory claims it moved) nor evidence a pin exists.
+    """
+    for m in _PIN_RE.finditer(text):
+        line_start = text.rfind("\n", 0, m.start()) + 1
+        if text[line_start:m.start()].lstrip().startswith("#"):
+            continue
+        return m
+    return None
+
+
+def _slug_dir_differs(live_dir: Path, staged_dir: Path) -> bool:
+    """Whether a kept slug's sync-owned files changed between the live package
+    and the staged next package (pre-swap, same filesystem).
+
+    Compares the FULL owned-file set — ``OWNED_SLUG_FILES`` — because a
+    usage-guide / endpoint-description enrichment changes only README.md or
+    example.py while the emitted module stays byte-identical; a presence flip
+    (example dropped or newly shipped) is a change too. The module's volatile
+    ``Generated at:`` stamp is normalized out (it differs on every render by
+    construction); ``__generated_with__`` is deliberately compared — an engine
+    bump IS a change. A non-UTF-8 artifact falls back to a raw byte compare.
+    """
+    for fn in sorted(OWNED_SLUG_FILES):
+        live, staged = live_dir / fn, staged_dir / fn
+        if live.exists() != staged.exists():
+            return True
+        if not live.exists():
+            continue
+        live_b, staged_b = live.read_bytes(), staged.read_bytes()
+        if fn == "__init__.py":
+            try:
+                live_t = _VOLATILE_HEADER_RE.sub("", live_b.decode("utf-8"))
+                staged_t = _VOLATILE_HEADER_RE.sub("", staged_b.decode("utf-8"))
+            except UnicodeDecodeError:
+                if live_b != staged_b:
+                    return True
+                continue
+            if live_t != staged_t:
+                return True
+        elif live_b != staged_b:
+            return True
+    return False
+
+
+def _restamp_scaffold_pin(root: Path, *, as_json: bool) -> None:
+    """Restamp ONLY the scaffold's exact ``parse-sdk==X`` pin to THIS engine —
+    never the whole file: the scaffold pyproject is user-editable (added
+    dev-deps, tool sections), and a full re-render silently reverted those edits
+    on every engine bump. The pin must track the engine (generated code
+    subclasses underscore-private runtime bases; the pin is the only thing
+    keeping ``uv sync`` from pulling a runtime the on-disk code was never
+    generated for). Atomic write; the restamp advisory prints only when the pin
+    moved — the missing-pin advisory repeats every sync by design. ``_find_pin``
+    skips comment lines and foreign deps, and the splice rewrites exactly the
+    matched span, so nothing else in the user-editable file can move."""
+    pin_path = root / "pyproject.toml"
+    try:
+        prior_pin_text = pin_path.read_text()
+    except OSError:
+        prior_pin_text = ""
+    m = _find_pin(prior_pin_text)
+    if m is None:
+        # Hand-mangled (or missing) file: rewriting it would clobber user
+        # content on a guess. Advise and continue — an absent pin lets the
+        # resolver drift silently, so CI's `parse sync --check` treats it as a
+        # finding.
+        if not as_json:
+            click.echo(click.style(
+                f"    · {pin_path} has no parse-sdk pin — expected "
+                f"`parse-sdk=={__version__}`; add it so `uv sync` installs the "
+                f"runtime this code was generated for", fg="yellow"))
+    elif m.group(1) != __version__:
+        _atomic_write_text(
+            pin_path,
+            prior_pin_text[:m.start()] + f"parse-sdk=={__version__}"
+            + prior_pin_text[m.end():])
+        if not as_json:
+            click.echo(click.style(
+                f"    · engine moved {m.group(1)} → {__version__}; scaffold pin "
+                f"restamped — run `uv sync` to align the installed runtime",
+                fg="yellow"))
+
+
+def _quarantine_staged_slugs(
+    next_pkg: Path, pkg: Path, prior: Dict[str, str], new_manifest: Dict[str, str]
+) -> List[dict]:
+    """Per-slug quarantine (carry-and-re-gate). A module finding must not abort
+    the whole sync: at fleet scale a single flagged spec would make promotion
+    permanently impossible for every healthy API. For a flagged slug, fall back
+    to its prior LIVE copy and RE-GATE that copy — nothing flagged is ever
+    promoted; a prior copy that fails the current gates ships absent. The slug's
+    manifest pin stays either way (the spec still renders; only its artifacts are
+    withheld), so the dir↔uuid mapping survives until the spec passes. Returns
+    one record per flagged slug: ``{slug, uuid, retained, failures}``."""
+    slug_to_uuid = {v: k for k, v in new_manifest.items()}
+    quarantined: List[dict] = []
+    for slug_dir in sorted(p for p in next_pkg.iterdir() if p.is_dir()):
+        slug = slug_dir.name
+        slug_failures = _staged_check_failures(slug_dir)
+        if not slug_failures:
+            continue
+        uuid = slug_to_uuid.get(slug)
+        # Re-sanitize the prior manifest slug before using it as a path
+        # component: a tampered/legacy manifest value (e.g. '../../etc') would
+        # otherwise make `pkg / prior_slug` escape the live tree and `copytree`
+        # read outside the package (audit SEC-1). safe_slug is idempotent on
+        # canonical slugs, so a legitimate prior dir still resolves; a traversal
+        # value is neutralized.
+        _prior_raw = prior.get(uuid) if uuid else None
+        prior_slug = safe_slug(_prior_raw) if _prior_raw else None
+        live_dir = (pkg / prior_slug) if prior_slug else None
+        shutil.rmtree(slug_dir, ignore_errors=True)
+        retained = False
+        if live_dir is not None and live_dir.is_dir():
+            try:
+                shutil.copytree(live_dir, slug_dir)
+            except FileNotFoundError:
+                pass  # concurrent promote moved the live tree; no prior copy
+            if slug_dir.is_dir():
+                if _staged_check_failures(slug_dir):
+                    # Fail-closed: the prior copy trips the CURRENT gates too
+                    # (e.g. an engine-side tightening) — never promote flagged
+                    # content, not even previously-live content.
+                    shutil.rmtree(slug_dir, ignore_errors=True)
+                else:
+                    retained = True
+        quarantined.append(
+            {"slug": slug, "uuid": uuid, "retained": retained,
+             "failures": slug_failures})
+    return quarantined
+
+
+def stage_check_swap(
+    cfg,
+    schemas: List[dict],
+    rendered: List[tuple],
+    skipped: List[dict],
+    *,
+    project: Path,
+    root: Path,
+    pkg: Path,
+    clean: bool,
+    check: bool = False,
+    as_json: bool = False,
+) -> None:
+    """Stage the next package, gate it, promote it atomically, and report.
+
+    Atomicity: the live package is never mutated in
+    place. The next package — committed scaffold + freshly generated slugs +
+    retained present-but-skipped slugs — is built on the same filesystem and
+    swapped via two ``os.replace`` calls with rollback, so a failure (mid-build,
+    a failed check, or an interrupted swap) leaves the live tree exactly as it
+    was. Orphaned slugs (uuids dropped from the server) are simply not carried
+    into the next package — that IS the prune. ``clean=True`` drops
+    the carried slugs too, rebuilding the payload from scratch — and, unlike the
+    old upfront ``rmtree``, only after the new payload is proven good.
+    """
+    prior = _load_manifest(pkg)
+    server_uuids = {s["id"] for s in schemas}
+    assigned = _assign_slugs([s for s, _ in rendered], prior)
+    rendered_by_uuid = {s["id"]: src for s, src in rendered}
+    generated = [{**s, "_assigned_slug": assigned[s["id"]]} for s, _ in rendered]
+    generated_slugs = {s["_assigned_slug"] for s in generated}
+    root_by_uuid = {s["id"]: resolve_root_name(s) for s in generated}
+
+    # carried = present-but-skipped slugs to retain; --clean drops them.
+    carried = {} if clean else _carry_skipped(prior, server_uuids, assigned)
+    new_manifest = {**carried, **assigned}
+
+    # Build the complete next package beside the live one (same filesystem → the
+    # promote is an atomic rename). Per-run UNIQUE names: two concurrent syncs
+    # each stage privately and the promote stays last-writer-wins atomic (the
+    # old fixed names + upfront rmtree let one run delete the other's
+    # half-built stage).
+    src_parent = pkg.parent
+    nonce = f"{os.getpid():x}-{secrets.token_hex(4)}"
+    next_pkg = src_parent / f".parse_apis.next-{nonce}"
+    old_pkg = src_parent / f".parse_apis.old-{nonce}"
+    _sweep_stale_stages(src_parent)
+    next_pkg.mkdir(parents=True)
+    coverage_by_uuid: Dict[str, List[Tuple[str, str]]] = {}
+    try:
+        # 1. freshly generated slugs — rendered, with per-example isolation.
+        example_shipped: Dict[str, bool] = {}
+        for s in generated:
+            slug = s["_assigned_slug"]
+            slug_dir = next_pkg / slug
+            slug_dir.mkdir(parents=True, exist_ok=True)
+            (slug_dir / "__init__.py").write_text(rendered_by_uuid[s["id"]])
+            # Render the example FIRST: its shippability drives the README/index
+            # example links. `render_example` is the single chokepoint that binds
+            # the self-import to the ASSIGNED slug (the sanitized/de-duped dir) and
+            # drops an unbindable/unparseable one; pass the RAW schema `s` so its
+            # root anchor matches the emitted module (rendered from `s`), and the
+            # assigned slug as the import-path target.
+            ex = docgen.render_example(s, slug=slug)
+            drop_reason = (_example_drop_reason(ex) if ex is not None else
+                           "its import couldn't be bound to the generated client")
+            shipped = ex is not None and drop_reason is None
+            if shipped:
+                (slug_dir / "example.py").write_text(ex)
+            elif (s.get("sdk_usage_example") or "").strip() and not as_json:
+                click.echo(click.style(
+                    f"    ⚠ dropped {slug}/example.py — {_safe_console(drop_reason)} — "
+                    f"fix the example for this API in Parse, then `parse sync`; the "
+                    f"client module is unaffected", fg="yellow", dim=True))
+            example_shipped[s["id"]] = shipped
+            (slug_dir / "README.md").write_text(
+                docgen.render_readme({**s, "slug": slug}, has_example=shipped))
+            coverage_by_uuid[s["id"]] = list(docgen.coverage_warnings(s))
+        # 2. retained present-but-skipped slugs (copied from the live package).
+        for slug in set(new_manifest.values()) - generated_slugs:
+            live_dir = pkg / slug
+            try:
+                if live_dir.is_dir():
+                    shutil.copytree(live_dir, next_pkg / slug)
+            except FileNotFoundError:
+                # A concurrent sync swapped the live tree away mid-copy. That
+                # run owns the retained slugs now; if the race persists, the
+                # promote below surfaces it cleanly instead of a raw traceback.
+                continue
+        # 3. Per-slug quarantine — flagged slugs fall back to a re-gated prior
+        # copy; nothing flagged is ever promoted (see _quarantine_staged_slugs).
+        quarantined = _quarantine_staged_slugs(next_pkg, pkg, prior, new_manifest)
+        quarantined_uuids = {q["uuid"] for q in quarantined if q["uuid"]}
+
+        # 4. manifest + cross-API index (from the post-quarantine survivor
+        # set: a retained prior copy keeps its entry; a removed module loses
+        # it — the index must never teach an import that would fail).
+        (next_pkg / MANIFEST_NAME).write_text(json.dumps(new_manifest, indent=2, sort_keys=True))
+        index_schemas = []
+        for s in generated:
+            slug = s["_assigned_slug"]
+            if not (next_pkg / slug).is_dir():
+                continue
+            has_ex = (example_shipped[s["id"]]
+                      if s["id"] not in quarantined_uuids
+                      else (next_pkg / slug / "example.py").exists())
+            index_schemas.append({**s, "slug": slug, "_has_example": has_ex})
+        if index_schemas:
+            # render_agents_index and render_claude_index produce byte-identical
+            # output (pinned by test_docgen.py); render once and write both to
+            # avoid a redundant second render and any drift between the files.
+            index_text = docgen.render_agents_index(index_schemas, base_url=cfg.base_url)
+            (next_pkg / "AGENTS.md").write_text(index_text)
+            (next_pkg / "CLAUDE.md").write_text(index_text)
+
+        # Self-test the next package's TOP-LEVEL artifacts before it touches the
+        # live tree. Slug dirs already passed (or were quarantined) above, so a
+        # finding here can only be in a NON-slug artifact written since — exactly
+        # _manifest.json / AGENTS.md / CLAUDE.md (the scaffold __init__.py /
+        # py.typed are written below, AFTER this check). Those have no per-slug
+        # fallback and still abort the whole sync. ``recursive=False`` so this
+        # pass does not re-read+re-parse every slug file the per-slug loop just
+        # gated (the dominant cost of a fleet sync). Under --check the failures
+        # join the findings report instead (nothing was going to be promoted
+        # anyway).
+        failures = _staged_check_failures(next_pkg, recursive=False)
+        if failures and not check:
+            click.echo(click.style(
+                "✗ sync aborted — staged artifacts failed pre-promotion checks:",
+                fg="red"), err=True)
+            for line in failures:
+                click.echo(click.style(
+                    f"    · {_safe_console(line)}", fg="red"), err=True)
+            click.echo(click.style(
+                "  Your existing generated payload was left unchanged.",
+                fg="yellow"), err=True)
+            shutil.rmtree(next_pkg, ignore_errors=True)
+            if as_json:
+                # The full-abort contract: failures alone on stdout (the
+                # human framing above went to stderr).
+                click.echo(json.dumps({"failures": failures}, indent=2))
+            sys.exit(1)
+
+        # 5. checks passed — add the committed scaffold from its SOURCE OF
+        # TRUTH (scaffold.render_*), not by copying the live tree: the copy
+        # was a check-then-copy race against a concurrent sync's promote and
+        # it propagated a stale scaffold forever. Trusted, so EXCLUDED from
+        # the gates above (re-scanning committed files would false-positive,
+        # e.g. the `__all__` error names tripping the entropy rule).
+        (next_pkg / "__init__.py").write_text(scaffold.render_scaffold_init())
+        (next_pkg / "py.typed").write_text("")
+
+        # 6. Change-visibility: per-uuid status, computed PRE-SWAP while live
+        # and staged trees coexist. `removed` is anything live before this sync
+        # that the next manifest drops (server orphans; with --clean, the
+        # un-carried skipped slugs too). Quarantined uuids get quarantine
+        # lines, not status lines.
+        status_by_uuid: Dict[str, str] = {}
+        for uuid in assigned:
+            if uuid in quarantined_uuids:
+                continue
+            if uuid not in prior:
+                status_by_uuid[uuid] = "new"
+            elif prior[uuid] != assigned[uuid]:
+                status_by_uuid[uuid] = f"renamed from {prior[uuid]}"
+            elif _slug_dir_differs(pkg / assigned[uuid], next_pkg / assigned[uuid]):
+                status_by_uuid[uuid] = "changed"
+            else:
+                status_by_uuid[uuid] = "unchanged"
+        removed_slugs = sorted(
+            prior[u] for u in prior.keys() - new_manifest.keys()
+        )
+        # The machine-readable result struct (the `--json` contract; the
+        # human renderer reads the same underlying maps). Warnings are plain
+        # strings at this layer.
+        result = {
+            "written": [
+                {"slug": s["_assigned_slug"], "id": s["id"],
+                 "root": root_by_uuid[s["id"]],
+                 "status": status_by_uuid.get(s["id"], "new"),
+                 "warnings": [{"severity": sev, "text": t}
+                              for sev, t in (coverage_by_uuid.get(s["id"]) or [])]}
+                for s in generated if s["id"] not in quarantined_uuids
+            ],
+            "skipped": [
+                {"slug": s.get("slug"), "id": s.get("id"),
+                 "reason": s.get("_skip_reason") or "un-modeled (no `resources` in spec)"}
+                for s in skipped
+            ],
+            "removed": removed_slugs,
+            "quarantined": [
+                {"slug": q["slug"], "id": q["uuid"], "retained": q["retained"],
+                 "findings": q["failures"]}
+                for q in quarantined
+            ],
+            "failures": list(failures),
+        }
+    except SystemExit:
+        raise
+    except BaseException:
+        shutil.rmtree(next_pkg, ignore_errors=True)
+        raise
+
+    if check:
+        # Dry run for CI: report what a real sync would do, then discard the
+        # staging tree — no promote, no pin restamp, no manifest write, no
+        # install. Strictness lives HERE (exit 1 on ANY finding, including
+        # would-be-quarantined slugs and a de-pinned scaffold); the real sync
+        # stays availability-first (exit 0 once the swap succeeds).
+        findings: List[str] = list(failures)
+        for q in quarantined:
+            for line in q["failures"]:
+                findings.append(f"would quarantine {q['slug']}: {line}")
+        try:
+            pin_text = (root / "pyproject.toml").read_text()
+        except OSError:
+            pin_text = ""
+        if _find_pin(pin_text) is None:
+            findings.append(
+                f"scaffold pyproject has no parse-sdk pin — expected "
+                f"parse-sdk=={__version__}")
+        shutil.rmtree(next_pkg, ignore_errors=True)
+        if as_json:
+            # The check-mode JSON contract: `failures` carries EVERY finding
+            # (scaffold-level, would-quarantine, missing pin), so a consumer
+            # may key pass/fail off `failures` alone — non-empty ⟺ exit 1.
+            # The structured per-slug detail stays in `quarantined`.
+            result["failures"] = list(findings)
+            click.echo(json.dumps(result, indent=2, sort_keys=True))
+            sys.exit(1 if findings else 0)
+        for s in generated:
+            if s["id"] in quarantined_uuids:
+                continue
+            status = status_by_uuid.get(s["id"], "new")
+            click.echo(f"    • {s['_assigned_slug']}  [{_safe_console(status)}]")
+        for slug in removed_slugs:
+            click.echo(f"    − {_safe_console(slug)}  [removed]")
+        for line in findings:
+            click.echo(click.style(
+                f"    ✗ {_safe_console(line)}", fg="red"), err=True)
+        if findings:
+            click.echo(click.style(
+                f"✗ check found {len(findings)} finding"
+                f"{'s' if len(findings) != 1 else ''} — a real sync would "
+                f"quarantine or abort; fix in Parse first.", fg="red"), err=True)
+            sys.exit(1)
+        click.echo("✓ check clean — a real sync would promote.")
+        return
+
+    # Atomic swap with rollback: live → old, next → live.
+    #  - First rename fails  → live tree untouched; just drop the staged next_pkg.
+    #  - Promote fails        → restore live from old_pkg.
+    # old_pkg is removed ONLY after a fully-confirmed swap. If the restore itself
+    # fails, old_pkg still holds the user's ONLY live copy, so it must never be
+    # rmtree'd on that path — deleting it would be unrecoverable data loss.
+    try:
+        os.replace(pkg, old_pkg)
+    except FileNotFoundError:
+        # The live package moved out from under us — a concurrent `parse sync`
+        # promoted first. The live tree is whole (last writer wins by design);
+        # surface the race as an actionable message, not a raw traceback.
+        shutil.rmtree(next_pkg, ignore_errors=True)
+        click.echo(click.style(
+            "✗ another `parse sync` promoted while this one was staging — "
+            "the live tree is consistent (owned by the other run). "
+            "Re-run `parse sync` if you need this run's snapshot.",
+            fg="red"), err=True)
+        sys.exit(1)
+    except BaseException:
+        shutil.rmtree(next_pkg, ignore_errors=True)
+        raise
+    try:
+        os.replace(next_pkg, pkg)
+    except BaseException:
+        os.replace(old_pkg, pkg)   # restore — raises (preserving old_pkg) if it can't
+        shutil.rmtree(next_pkg, ignore_errors=True)
+        raise
+    # Swap confirmed — old_pkg and next_pkg are now disposable.
+    shutil.rmtree(old_pkg, ignore_errors=True)
+    shutil.rmtree(next_pkg, ignore_errors=True)
+
+    # Restamp the scaffold's engine pin to THIS engine (atomic, pin-span only).
+    _restamp_scaffold_pin(root, as_json=as_json)
+
+    # Refresh the committed top-level agent pointer from its source of truth —
+    # the same post-swap moment the pin restamp touches the top-level pyproject.
+    # Content-compared so an unchanged sync makes no git diff and no spurious
+    # mtime churn. Unreached under --check (it returns before the swap), so a dry
+    # run never mutates the pointer.
+    pointer = scaffold.render_root_pointer()
+    for _name in ("AGENTS.md", "CLAUDE.md"):
+        _ptr = root / _name
+        try:
+            _current = _ptr.read_text()
+        except OSError:
+            _current = None
+        if _current != pointer:
+            _atomic_write_text(_ptr, pointer)
+
+    if as_json:
+        # Machine-readable result on stdout; the human report below is
+        # suppressed entirely (stderr errors already went out on their own).
+        click.echo(json.dumps(result, indent=2, sort_keys=True))
+        return
+
+    _STATUS_COLOR = {"new": "green", "changed": "yellow", "unchanged": None}
+    promoted = [s for s in generated if s["id"] not in quarantined_uuids]
+    if promoted:
+        click.echo(
+            f"✓ wrote {len(promoted)} typed module"
+            f"{'s' if len(promoted) != 1 else ''} to "
+            f"{click.style(str(pkg), fg='cyan')}"
+        )
+        for s in promoted:
+            slug = s["_assigned_slug"]
+            root_name = root_by_uuid[s["id"]]
+            status = status_by_uuid.get(s["id"], "new")
+            color = _STATUS_COLOR.get(status, "yellow")  # renamed → yellow
+            marker = (
+                click.style(f"[{_safe_console(status)}]", fg=color)
+                if color else click.style(f"[{_safe_console(status)}]", dim=True)
+            )
+            click.echo(
+                f"    • {click.style(slug, fg='cyan')}  "
+                f"({root_name}, {len(_schema_resources(s))} resources, "
+                f"{len(_schema_endpoint_names(s))} endpoints)  {marker}"
+            )
+    for slug in removed_slugs:
+        click.echo(f"    − {click.style(_safe_console(slug), fg='red')}  [removed]")
+
+    if quarantined:
+        for q in quarantined:
+            outcome = (
+                "prior copy retained (stale until the spec passes)"
+                if q["retained"] else
+                f"module removed; imports of parse_apis.{q['slug']} will fail "
+                f"until it passes"
+            )
+            click.echo(click.style(
+                f"    ⚠ {q['slug']}  [quarantined — {outcome}]", fg="yellow"))
+            for line in q["failures"]:
+                click.echo(click.style(
+                    f"        · {_safe_console(line)} — fix this API in Parse, "
+                    f"then `parse sync`", fg="yellow", dim=True))
+        n_ret = sum(1 for q in quarantined if q["retained"])
+        n_rem = len(quarantined) - n_ret
+        click.echo(click.style(
+            f"    ⚠ {len(quarantined)} API{'s' if len(quarantined) != 1 else ''} "
+            f"quarantined ({n_ret} prior cop{'ies' if n_ret != 1 else 'y'} "
+            f"retained, {n_rem} removed) — healthy APIs promoted normally.",
+            fg="yellow"))
+
+    # Coverage warnings, gated on change-visibility: a warning teaches once
+    # (when the API is new or its payload changed), then aggregates — an
+    # unchanged API re-printing the same ⚠ every sync trains users to ignore
+    # the channel. Within the printed set, severity decides the shape:
+    # STRUCTURAL warnings (dead code, suppressed factory, prose contradicting
+    # the emitted signature) print per-line; ENRICHMENT warnings (missing
+    # narrative) collapse to one line per API — at fleet scale dozens of
+    # identical "endpoint has no description" advisories drown the two real
+    # problems.
+    # Quarantined uuids are excluded — their quarantine lines own the channel.
+    warned_suppressed = 0
+    total_enrichment = 0
+    apis_with_enrichment = 0
+    for s in promoted:
+        warns = coverage_by_uuid.get(s["id"]) or []
+        if not warns:
+            continue
+        if status_by_uuid.get(s["id"]) == "unchanged":
+            warned_suppressed += 1
+            continue
+        structural = [t for sev, t in warns if sev == "structural"]
+        enrichment = [t for sev, t in warns if sev == "enrichment"]
+        for w in structural:
+            click.echo(click.style(f"    ⚠ {_safe_console(w)}", fg="yellow"))
+        if enrichment:
+            total_enrichment += len(enrichment)
+            apis_with_enrichment += 1
+            click.echo(click.style(
+                f"    ⚠ {s['_assigned_slug']}: {len(enrichment)} enrichment gap"
+                f"{'s' if len(enrichment) != 1 else ''} — README renders "
+                f"reference + example until enriched in Parse",
+                fg="yellow", dim=True))
+    # On an all-new run (init's first sync by construction) add the grand
+    # total, so 53 fresh APIs read as one number, not 53 lines.
+    if (apis_with_enrichment > 1 and promoted
+            and all(status_by_uuid.get(s["id"], "new") == "new" for s in promoted)):
+        click.echo(click.style(
+            f"    ⚠ {total_enrichment} enrichment gap"
+            f"{'s' if total_enrichment != 1 else ''} across "
+            f"{apis_with_enrichment} APIs — enrich in Parse to upgrade the READMEs",
+            fg="yellow", dim=True))
+    if warned_suppressed:
+        click.echo(click.style(
+            f"    ⚠ {warned_suppressed} unchanged API"
+            f"{'s' if warned_suppressed != 1 else ''} still ha"
+            f"{'ve' if warned_suppressed != 1 else 's'} enrichment warnings "
+            f"(shown when an API is new or changes)", fg="yellow", dim=True))
+    if skipped:
+        click.echo()
+        click.echo(click.style(
+            f"⚠ skipped {len(skipped)} un-modeled API"
+            f"{'s' if len(skipped) != 1 else ''} (no `resources` in spec):",
+            fg="yellow",
+        ))
+        for s in skipped[:10]:
+            click.echo(f"    · {_safe_console(s['slug'])}  {_safe_console(s['id'])}")
+        if len(skipped) > 10:
+            click.echo(f"    · … and {len(skipped) - 10} more")
+        click.echo(click.style(
+            "  Revise these through Parse so the agent fills in the SDK layer.",
+            fg="yellow",
+        ))
+    if promoted:
+        click.echo()
+        click.echo("Usage:")
+        for s in promoted[:3]:
+            slug = s["_assigned_slug"]
+            click.echo(f"    from parse_apis.{slug} import {root_by_uuid[s['id']]}")
+        if len(promoted) > 3:
+            # Without this a cold agent reading the three example lines
+            # concludes the project has three APIs.
+            click.echo(
+                f"    … and {len(promoted) - 3} more — "
+                f"see {(pkg / 'CLAUDE.md').relative_to(project)}")
+        click.echo()
+        click.echo(click.style(
+            "`parse_apis` is an installed editable package — imports resolve from any "
+            "directory; re-run `parse sync` to refresh.",
+            dim=True,
+        ))
+
+    # Agent-ready next steps — printed whenever this sync introduced at least
+    # one NEW API (init's first sync is all-new by construction), absent on an
+    # all-unchanged refresh. Fixed block, plain text, no new nouns.
+    if any(status_by_uuid.get(s["id"], "new") == "new" for s in promoted):
+        index_rel = (pkg / "CLAUDE.md").relative_to(project)
+        click.echo()
+        click.echo("Next steps:")
+        click.echo(
+            f"    1. Read {index_rel} — start with Conventions "
+            f"({len(index_schemas)} API"
+            f"{'s' if len(index_schemas) != 1 else ''} indexed).")
+        click.echo(
+            "    2. Then an API's example.py (runnable start), then its "
+            "README.md (full reference).")
+        click.echo(
+            "    3. Pass limit= on list/search calls unless exhaustive traversal "
+            "is intended — each page is a live, billed request.")
+        click.echo(
+            "    4. `uv run parse list` shows every API; `uv run parse sync` "
+            "refreshes after edits in Parse.")