sable-sphynx 0.7.0.dev0__py3-none-any.whl

sphynx/documentation_candidate.py

@@ -0,0 +1,939 @@
+"""Review-only documentation candidates, extracted without importing the SDK.
+
+The frozen v1 exporter remains independent. This format binds the actual wheel,
+the complete reviewed source snapshot, curated guides and a static HTML view.
+AST extraction reads declarations; it never executes inspected source or examples.
+"""
+from __future__ import annotations
+
+import argparse
+import ast
+import copy
+from email import policy
+from email.parser import Parser
+import hashlib
+import html
+import json
+from pathlib import Path, PurePosixPath
+import re
+import runpy
+import sys
+import tomllib
+from urllib.parse import urlsplit
+import zipfile
+
+
+EXPORTER_VERSION = "candidate.2"
+CONTENT_SCHEMA = "sphynx.docs.candidate-content.v1"
+CATALOG_SCHEMA = "sphynx.docs.candidate-catalog.v2"
+BUNDLE_SCHEMA = "sphynx.docs.candidate-bundle.v1"
+MANIFEST_SCHEMA = "sphynx.docs.candidate-manifest.v1"
+MAX_JSON_BYTES = 12_000_000
+MAX_SOURCE_BYTES = 100_000_000
+_HASH = re.compile(r"[0-9a-f]{64}")
+_IDENTIFIER = re.compile(r"[a-zA-Z0-9][a-zA-Z0-9._-]{0,255}")
+_PRIVATE = re.compile(
+    r"gs://|[A-Za-z]:[\\/](?:Users|ProgramData)[\\/]|"
+    r"(?:^|[\\/])\.agent[\\/]|<\s*(?:script|iframe|object|svg)\b|javascript:|"
+    r"-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----|sk-[A-Za-z0-9]{20,}", re.I)
+_SECRET_KEY = re.compile(
+    r"^(?:token|password|secret|credentials?|raw_questions?|raw_labels?|answer_capture|"
+    r"weights?|fitted_state|gcs_uri|internal_path|environment)$", re.I)
+_FILES = ("catalog.json", "content.json", "source-identity.json", "index.html")
+_MEMBERS = {*_FILES, "bundle.json", "manifest.json"}
+_CORE_SOURCE = {
+    "pyproject.toml", "tools/release/source_allowlist.json", "src/sphynx/__init__.py",
+    "src/sphynx/documentation.py", "src/sphynx/documentation_candidate.py",
+    "src/sphynx/workflows.py", "src/sphynx/workflow_contracts.py",
+    "src/sphynx/workflow_registry.py", "src/sphynx/assessment_contracts.py",
+    "src/sphynx/workflow_defaults.py", "src/sphynx/rerank_workflow.py",
+    "tools/export_documentation.py",
+}
+
+
+class CandidateDocumentationError(ValueError):
+    """Malformed, stale, incompatible or unapproved candidate documentation."""
+
+
+def _require(condition, message):
+    if not condition:
+        raise CandidateDocumentationError(message)
+
+
+def _sha(raw):
+    return hashlib.sha256(raw).hexdigest()
+
+
+def _canonical(value):
+    try:
+        raw = json.dumps(value, ensure_ascii=False, sort_keys=True,
+                         separators=(",", ":"), allow_nan=False).encode("utf-8")
+    except (ValueError, TypeError, UnicodeError, RecursionError) as exc:
+        raise CandidateDocumentationError("content is outside safe JSON") from exc
+    _require(len(raw) <= MAX_JSON_BYTES, "JSON exceeds candidate size limit")
+    return raw
+
+
+def _safe_json(value, *, confidentiality=True):
+    """Bound structure and reject non-finite values, executable/private content."""
+    nodes = 0
+
+    def visit(item, depth):
+        nonlocal nodes
+        nodes += 1
+        _require(depth <= 40 and nodes <= 300_000, "JSON exceeds structural limits")
+        if item is None or type(item) in (bool, int):
+            return
+        if type(item) is float:
+            _require(item == item and abs(item) != float("inf"), "non-finite JSON number")
+        elif type(item) is str:
+            _require(len(item) <= 200_000, "JSON string exceeds size limit")
+            _require(not confidentiality or not _PRIVATE.search(item),
+                     "unapproved private locator or executable content")
+        elif type(item) is list:
+            for child in item:
+                visit(child, depth + 1)
+        elif type(item) is dict:
+            for key, child in item.items():
+                _require(type(key) is str, "JSON keys must be strings")
+                _require(not confidentiality or not _SECRET_KEY.fullmatch(key),
+                         "unapproved protected-data field")
+                visit(key, depth + 1)
+                visit(child, depth + 1)
+        else:
+            raise CandidateDocumentationError("value is outside safe JSON")
+    visit(value, 0)
+    _canonical(value)
+
+
+def _pairs(items):
+    result = {}
+    for key, value in items:
+        _require(key not in result, "duplicate JSON key")
+        result[key] = value
+    return result
+
+
+def _read(path, limit=MAX_JSON_BYTES):
+    path = Path(path)
+    _require(path.is_file() and not path.is_symlink(), "input is missing or symlinked")
+    _require(path.stat().st_size <= limit, "input exceeds size limit")
+    raw = path.read_bytes()
+    _require(len(raw) <= limit, "input exceeds size limit")
+    return raw
+
+
+def _json(path):
+    try:
+        value = json.loads(_read(path).decode("utf-8"), object_pairs_hook=_pairs,
+                           parse_constant=lambda _: (_ for _ in ()).throw(
+                               CandidateDocumentationError("non-finite JSON number")))
+    except (ValueError, UnicodeError, RecursionError) as exc:
+        raise CandidateDocumentationError("invalid candidate JSON") from exc
+    _safe_json(value)
+    return value
+
+
+def _keys(value, keys, name):
+    _require(type(value) is dict and set(value) == set(keys.split()),
+             f"{name} has missing or unapproved keys")
+
+
+def _text(value, name):
+    _require(type(value) is str and bool(value.strip()) and len(value) <= 20_000,
+             f"{name} must be nonempty bounded text")
+
+
+def _relative(value):
+    _require(type(value) is str and value and "\\" not in value and ":" not in value,
+             "unsafe relative path")
+    path = PurePosixPath(value)
+    _require(not path.is_absolute() and all(part not in ("", ".", "..") for part in value.split("/")),
+             "unsafe relative path")
+    for part in path.parts:
+        _require(part.rstrip(" .") == part and not any(ord(c) < 32 or c in '<>"|?*' for c in part),
+                 "nonportable relative path")
+        _require(part.split(".")[0].upper() not in
+                 {"CON", "PRN", "AUX", "NUL", "CONIN$", "CONOUT$",
+                  *(f"COM{i}" for i in "123456789"), *(f"LPT{i}" for i in "123456789")},
+                 "reserved relative path")
+    return path
+
+
+def _source_path(root, relative):
+    relative = _relative(relative)
+    path = root.joinpath(*relative.parts)
+    _require(path.is_file() and path.resolve().is_relative_to(root),
+             "source input is missing or outside the source root")
+    _require(not any(parent.is_symlink() for parent in (path, *path.parents) if parent != root.parent),
+             "symlinked source input")
+    return path
+
+
+def _unique(items, name):
+    _require(type(items) is list and bool(items), f"{name} must be a nonempty array")
+    identifiers = []
+    for item in items:
+        _require(type(item) is dict and type(item.get("id")) is str
+                 and _IDENTIFIER.fullmatch(item["id"]), f"{name} has invalid IDs")
+        identifiers.append(item["id"])
+    _require(len(identifiers) == len(set(identifiers)), f"{name} has duplicate IDs")
+    return set(identifiers)
+
+
+def validate_content(content):
+    """Validate the exact curated candidate grammar; never execute its examples."""
+    _safe_json(content)
+    _keys(content, "schema_version id sdk_version pages", "candidate content")
+    _require(content["schema_version"] == CONTENT_SCHEMA, "unsupported candidate content schema")
+    _require(type(content["id"]) is str and _IDENTIFIER.fullmatch(content["id"]), "invalid candidate ID")
+    _text(content["sdk_version"], "SDK version")
+    _unique(content["pages"], "pages")
+    pages = {page["id"]: page for page in content["pages"]}
+    for page in content["pages"]:
+        _keys(page, "id title category summary sections", "page")
+        for key in ("title", "category", "summary"):
+            _text(page[key], "page " + key)
+        _unique(page["sections"], "sections")
+        for section in page["sections"]:
+            _keys(section, "id title paragraphs blocks tables links", "section")
+            _text(section["title"], "section title")
+            for key in ("paragraphs", "blocks", "tables", "links"):
+                _require(type(section[key]) is list, "section members must be arrays")
+            for paragraph in section["paragraphs"]:
+                _text(paragraph, "paragraph")
+            for block in section["blocks"]:
+                _keys(block, "language code execution", "block")
+                _require(block["language"] in {"python", "powershell", "bash", "text", "json"},
+                         "unsupported example language")
+                _require(block["execution"] in {"fixture", "read_only", "metadata_only", "paid_remote"},
+                         "unsupported execution boundary")
+                _text(block["code"], "example code")
+                _require(not block["code"].startswith((">>>", "PS ", "$ ")), "examples must omit prompts")
+                try:
+                    if block["language"] == "python":
+                        ast.parse(block["code"], feature_version=(3, 11))
+                    elif block["language"] == "json":
+                        _safe_json(json.loads(block["code"], object_pairs_hook=_pairs))
+                except (SyntaxError, ValueError, RecursionError) as exc:
+                    raise CandidateDocumentationError("invalid example syntax") from exc
+            for table in section["tables"]:
+                _keys(table, "columns rows", "table")
+                _require(type(table["columns"]) is list and bool(table["columns"])
+                         and type(table["rows"]) is list, "table must have columns and rows")
+                for cell in table["columns"]:
+                    _text(cell, "table column")
+                for row in table["rows"]:
+                    _require(type(row) is list and len(row) == len(table["columns"]), "table row width differs")
+                    for cell in row:
+                        _require(type(cell) is str, "table cells must be strings")
+            for link in section["links"]:
+                _keys(link, "label url", "link")
+                _text(link["label"], "link label")
+                url = link["url"]
+                _require(type(url) is str, "link URL must be text")
+                if url.startswith("#"):
+                    pieces = url[1:].split("/")
+                    target = pages.get(pieces[0])
+                    _require(1 <= len(pieces) <= 2 and target is not None, "invalid internal page link")
+                    _require(len(pieces) == 1 or pieces[1] in {item["id"] for item in target["sections"]},
+                             "invalid internal section link")
+                else:
+                    try:
+                        parsed = urlsplit(url)
+                    except ValueError as exc:
+                        raise CandidateDocumentationError("invalid external link") from exc
+                    _require(parsed.scheme == "https" and bool(parsed.hostname)
+                             and parsed.username is None and parsed.password is None,
+                             "external links must be credential-free HTTPS")
+
+
+def _parameters(args, *, bound=False):
+    args = copy.deepcopy(args)
+    if bound and args.args and args.args[0].arg in {"self", "cls"}:
+        args.args.pop(0)
+    positions = [*args.posonlyargs, *args.args]
+    required = len(positions) - len(args.defaults)
+    rows = []
+    for index, arg in enumerate(positions):
+        default = None if index < required else args.defaults[index - required]
+        rows.append({"name": arg.arg, "annotation": ast.unparse(arg.annotation) if arg.annotation else None,
+                     "kind": "positional_only" if index < len(args.posonlyargs) else "positional_or_keyword",
+                     "required": index < required, "default": ast.unparse(default) if default is not None else None})
+    if args.vararg:
+        arg = args.vararg
+        rows.append({"name": arg.arg, "annotation": ast.unparse(arg.annotation) if arg.annotation else None,
+                     "kind": "var_positional", "required": False, "default": None})
+    for arg, default in zip(args.kwonlyargs, args.kw_defaults):
+        rows.append({"name": arg.arg, "annotation": ast.unparse(arg.annotation) if arg.annotation else None,
+                     "kind": "keyword_only", "required": default is None,
+                     "default": ast.unparse(default) if default is not None else None})
+    if args.kwarg:
+        arg = args.kwarg
+        rows.append({"name": arg.arg, "annotation": ast.unparse(arg.annotation) if arg.annotation else None,
+                     "kind": "var_keyword", "required": False, "default": None})
+    return ast.unparse(args), rows
+
+
+class _Source:
+    def __init__(self, root):
+        self.root = Path(root).resolve(strict=True)
+        self.trees = {}
+
+    def tree(self, module):
+        if module not in self.trees:
+            relative = "src/sphynx/" + (module.replace(".", "/") + ".py" if module else "__init__.py")
+            path = _source_path(self.root, relative)
+            try:
+                tree = ast.parse(_read(path).decode("utf-8-sig"), filename=relative, feature_version=(3, 11))
+            except (SyntaxError, UnicodeError) as exc:
+                raise CandidateDocumentationError("invalid source syntax: " + relative) from exc
+            self.trees[module] = (tree, relative)
+        return self.trees[module][0]
+
+    def imported(self, module, node, name):
+        if node.level:
+            parent = module.split(".")[:-node.level] if module else []
+            destination = ".".join([*parent, *([node.module] if node.module else [])])
+        else:
+            _require(node.module is not None and node.module.startswith("sphynx."),
+                     "public API resolves outside the SDK")
+            destination = node.module.removeprefix("sphynx.")
+        return destination, name
+
+    def resolve(self, module, name, trail=()):
+        key = (module, name)
+        _require(key not in trail and len(trail) < 30, "cyclic or excessive public alias chain")
+        tree = self.tree(module)
+        # Class-body aliases are resolved before their enclosing class import.
+        if "." in name:
+            head, tail = name.split(".", 1)
+            owner_module, owner_name, owner = self.resolve(module, head, (*trail, key))
+            _require(isinstance(owner, ast.ClassDef), "public method owner is not a class")
+            for node in reversed(owner.body):
+                if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and node.name == tail:
+                    return owner_module, owner_name + "." + tail, node
+                if isinstance(node, ast.Assign) and any(isinstance(t, ast.Name) and t.id == tail for t in node.targets):
+                    _require(isinstance(node.value, ast.Name), "unsupported class-body alias")
+                    return self.resolve(owner_module, owner_name + "." + node.value.id, (*trail, key))
+            raise CandidateDocumentationError("missing declared public method: " + name)
+        for node in reversed(tree.body):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)) and node.name == name:
+                return module, name, node
+            if isinstance(node, (ast.Assign, ast.AnnAssign)):
+                targets = node.targets if isinstance(node, ast.Assign) else [node.target]
+                if any(isinstance(t, ast.Name) and t.id == name for t in targets):
+                    if isinstance(node.value, ast.Name):
+                        return self.resolve(module, node.value.id, (*trail, key))
+                    return module, name, node
+            if isinstance(node, ast.ImportFrom):
+                for alias in node.names:
+                    if (alias.asname or alias.name) == name:
+                        destination, original = self.imported(module, node, alias.name)
+                        return self.resolve(destination, original, (*trail, key))
+        raise CandidateDocumentationError("missing declared public API: " + (module + "." + name))
+
+    def literal(self, module, node, trail=()):
+        if isinstance(node, (ast.List, ast.Tuple)):
+            return [self.literal(module, item, trail) for item in node.elts]
+        if isinstance(node, ast.Dict):
+            return {self.literal(module, key, trail): self.literal(module, item, trail)
+                    for key, item in zip(node.keys, node.values)}
+        try:
+            return ast.literal_eval(node)
+        except (ValueError, TypeError):
+            pass
+        if isinstance(node, ast.Name):
+            resolved_module, name, declaration = self.resolve(module, node.id)
+            _require((resolved_module, name) not in trail, "cyclic metadata constant")
+            _require(isinstance(declaration, (ast.Assign, ast.AnnAssign)), "metadata constant is not literal")
+            return self.literal(resolved_module, declaration.value, (*trail, (resolved_module, name)))
+        raise CandidateDocumentationError("metadata expression is not a declared literal")
+
+    def exports(self):
+        bindings, values, public = {}, {}, []
+        for node in self.tree("").body:
+            if isinstance(node, ast.ImportFrom):
+                for alias in node.names:
+                    bindings[alias.asname or alias.name] = self.imported("", node, alias.name)
+            elif isinstance(node, ast.Assign):
+                for target in node.targets:
+                    if not isinstance(target, ast.Name):
+                        continue
+                    if target.id in {"_WORKFLOW_EXPORTS", "_RESEARCH_EXPORTS"}:
+                        values[target.id] = ast.literal_eval(node.value)
+                        for name, value in values[target.id].items():
+                            bindings[name] = (value, name) if isinstance(value, str) else tuple(value)
+                    elif target.id == "__all__":
+                        public = ast.literal_eval(node.value)
+                    elif isinstance(node.value, ast.Name) and node.value.id in bindings:
+                        bindings[target.id] = bindings[node.value.id]
+            elif isinstance(node, ast.AugAssign) and isinstance(node.target, ast.Name) and node.target.id == "__all__":
+                if isinstance(node.value, ast.Call) and isinstance(node.value.func, ast.Name) and node.value.func.id == "list":
+                    public.extend(values[node.value.args[0].id])
+                else:
+                    public.extend(ast.literal_eval(node.value))
+        _require(len(public) == len(set(public)), "root public exports contain duplicates")
+        _require(set(public).issubset(bindings), "root public export has no static binding")
+        return {name: bindings[name] for name in sorted(public)}
+
+    def function(self, module, canonical, node, public_name):
+        bound = "." in canonical
+        arguments, parameters = _parameters(node.args, bound=bound)
+        returns = ast.unparse(node.returns) if node.returns else None
+        return {"name": public_name, "target": "sphynx." + module + "." + canonical,
+                "alias_of": None if public_name == canonical.split(".")[-1] else canonical,
+                "signature": public_name + "(" + arguments + ")" + (" -> " + returns if returns else ""),
+                "parameters": parameters, "returns": returns,
+                "summary": (ast.get_docstring(node) or "").split("\n")[0],
+                "decorators": [ast.unparse(item) for item in node.decorator_list],
+                "source_line": node.lineno}
+
+    def entry(self, public_name, module, original):
+        defining_module, canonical, node = self.resolve(module, original)
+        path = self.trees[defining_module][1]
+        result = {"id": "sphynx." + public_name, "target": "sphynx." + defining_module + "." + canonical,
+                  "kind": "constant", "alias_of": None if public_name == canonical else canonical,
+                  "signature": None, "parameters": [], "returns": None, "summary": "",
+                  "source_path": path, "source_line": node.lineno, "fields": [], "methods": [], "value": None}
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            function = self.function(defining_module, canonical, node, public_name)
+            result.update({key: function[key] for key in ("signature", "parameters", "returns", "summary")})
+            result["kind"] = "function"
+        elif isinstance(node, ast.ClassDef):
+            result.update(kind="class", summary=(ast.get_docstring(node) or "").split("\n")[0])
+            dataclass = next((item for item in node.decorator_list
+                              if (isinstance(item, ast.Name) and item.id == "dataclass")
+                              or (isinstance(item, ast.Call) and isinstance(item.func, ast.Name)
+                                  and item.func.id == "dataclass")), None)
+            options = {kw.arg: ast.literal_eval(kw.value) for kw in dataclass.keywords} if isinstance(dataclass, ast.Call) else {}
+            for item in node.body:
+                if not isinstance(item, ast.AnnAssign) or not isinstance(item.target, ast.Name):
+                    continue
+                name, default, factory = item.target.id, item.value, None
+                init, keyword_only = True, options.get("kw_only", False)
+                if isinstance(default, ast.Call) and isinstance(default.func, ast.Name) and default.func.id == "field":
+                    keywords = {kw.arg: kw.value for kw in default.keywords}
+                    init = ast.literal_eval(keywords.get("init", ast.Constant(True)))
+                    keyword_only = ast.literal_eval(keywords.get("kw_only", ast.Constant(keyword_only)))
+                    factory = ast.unparse(keywords["default_factory"]) if "default_factory" in keywords else None
+                    default = keywords.get("default")
+                result["fields"].append({"name": name, "annotation": ast.unparse(item.annotation),
+                                         "default": ast.unparse(default) if default is not None else None,
+                                         "default_factory": factory, "init": init,
+                                         "keyword_only": keyword_only, "private": name.startswith("_")})
+            methods = {}
+            for item in node.body:
+                if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    if not item.name.startswith("_") or item.name == "__init__":
+                        methods[item.name] = item.name
+                elif isinstance(item, ast.Assign) and isinstance(item.value, ast.Name):
+                    for target in item.targets:
+                        if isinstance(target, ast.Name) and not target.id.startswith("_"):
+                            methods[target.id] = item.value.id
+            for name in sorted(methods):
+                m, c, function = self.resolve(defining_module, canonical + "." + name)
+                result["methods"].append(self.function(m, c, function, name))
+            constructor = next((item for item in result["methods"] if item["name"] == "__init__"), None)
+            if constructor:
+                result["signature"] = public_name + constructor["signature"][len("__init__"):]
+                result["parameters"] = constructor["parameters"]
+            elif dataclass is not None and options.get("init", True):
+                fields = [item for item in result["fields"] if item["init"]]
+                result["parameters"] = [
+                    {"name": item["name"], "annotation": item["annotation"],
+                     "kind": "keyword_only" if item["keyword_only"] else "positional_or_keyword",
+                     "required": item["default"] is None and item["default_factory"] is None,
+                     "default": item["default"] if item["default_factory"] is None else "<factory:" + item["default_factory"] + ">"}
+                    for item in fields]
+                pieces, keyword_marker = [], False
+                for item in result["parameters"]:
+                    if item["kind"] == "keyword_only" and not keyword_marker:
+                        pieces.append("*")
+                        keyword_marker = True
+                    pieces.append(item["name"] + ": " + item["annotation"]
+                                  + ("" if item["required"] else " = " + item["default"]))
+                result["signature"] = public_name + "(" + ", ".join(pieces) + ")"
+        else:
+            result["value"] = self.literal(defining_module, node.value)
+        return result
+
+
+def extract_catalog(source_root):
+    """Read root exports, real alias targets and extension declarations by AST."""
+    source = _Source(source_root)
+    project = tomllib.loads(_read(_source_path(source.root, "pyproject.toml")).decode("utf-8-sig"))["project"]
+    runtime_version = source.literal("", next(node.value for node in source.tree("").body
+        if isinstance(node, ast.Assign) and any(isinstance(t, ast.Name) and t.id == "__version__" for t in node.targets)))
+    _require(project["version"] == runtime_version, "package/runtime version mismatch")
+    exports = [source.entry(name, *binding) for name, binding in source.exports().items()]
+    # The default is one convenience binding. Configured registry factories are
+    # derived from the same public AST entries; their constructors remain the
+    # authority for required operator configuration and capability admission.
+    factories = [{key: entry[key] for key in (
+        "id", "target", "signature", "parameters", "summary", "source_path", "source_line")}
+        for entry in exports if entry["kind"] == "function" and entry["returns"] == "WorkflowRegistry"]
+    bootstrap = source.tree("workflow_defaults")
+    _require(any(isinstance(node, ast.ImportFrom) and node.module == "rerank_workflow"
+                 and any(alias.name == "build_rerank_registry" for alias in node.names)
+                 for node in ast.walk(bootstrap)), "built-in bootstrap declaration changed")
+    factory = next(node for node in bootstrap.body if isinstance(node, ast.FunctionDef)
+                   and node.name == "default_workflow_registry")
+    returns = [node for node in ast.walk(factory) if isinstance(node, ast.Return)]
+    _require(len(returns) == 1 and isinstance(returns[0].value, ast.Call)
+             and isinstance(returns[0].value.func, ast.Name)
+             and returns[0].value.func.id == "build_rerank_registry"
+             and not returns[0].value.args and not returns[0].value.keywords,
+             "built-in bootstrap selection changed; review its metadata extractor")
+    backend_tree = source.tree("rerank_workflow")
+    descriptor = next(node.value for node in backend_tree.body if isinstance(node, ast.Assign)
+                      and any(isinstance(t, ast.Name) and t.id == "_DESCRIPTOR" for t in node.targets))
+    _require(isinstance(descriptor, ast.Call) and isinstance(descriptor.func, ast.Name)
+             and descriptor.func.id == "BackendDescriptor" and not descriptor.args,
+             "built-in descriptor must be an explicit metadata declaration")
+    backend = {item.arg: source.literal("rerank_workflow", item.value) for item in descriptor.keywords}
+    # Reuse only the frozen exporter's pure AST schema reader, without its lock.
+    frozen = runpy.run_path(str(Path(__file__).with_name("documentation.py")))
+    parameters = frozen["extract_parameter_schemas"](source.root)
+    result = {"schema_version": CATALOG_SCHEMA, "sdk_version": runtime_version,
+              "distribution": project["name"], "exports": exports,
+              "builtin_backends": [backend], "registry_factories": factories,
+              "native_parameter_schemas": parameters,
+              "boundaries": {"metadata_only": True, "live_hosted_verified": False,
+                             "catalog_entry_is_execution_admission": False,
+                             "candidate_source_verified_by_local_builtin": False}}
+    _safe_json(result)
+    return result
+
+
+def _validate_catalog(catalog):
+    _safe_json(catalog)
+    _keys(catalog, "schema_version sdk_version distribution exports builtin_backends registry_factories native_parameter_schemas boundaries",
+          "candidate catalog")
+    _require(catalog["schema_version"] == CATALOG_SCHEMA, "unsupported candidate catalog schema")
+    _unique(catalog["exports"], "public exports")
+    _text(catalog["sdk_version"], "catalog SDK version")
+    _text(catalog["distribution"], "catalog distribution")
+    for entry in catalog["exports"]:
+        _keys(entry, "id target kind alias_of signature parameters returns summary source_path source_line fields methods value",
+              "public API")
+        _require(entry["kind"] in {"class", "function", "constant"}, "invalid API kind")
+        _text(entry["target"], "API target")
+        _require(type(entry["summary"]) is str, "API summary must be text")
+        _require(all(entry[key] is None or type(entry[key]) is str
+                     for key in ("alias_of", "signature", "returns")), "invalid optional API text")
+        _relative(entry["source_path"])
+        _require(type(entry["source_line"]) is int and entry["source_line"] > 0, "invalid source line")
+        _require(type(entry["parameters"]) is list and type(entry["fields"]) is list
+                 and type(entry["methods"]) is list, "API collections must be arrays")
+        for method in entry["methods"]:
+            _keys(method, "name target alias_of signature parameters returns summary decorators source_line", "API method")
+            for key in ("name", "target", "signature"):
+                _text(method[key], "method " + key)
+            _require(type(method["summary"]) is str
+                     and type(method["decorators"]) is list
+                     and all(type(item) is str for item in method["decorators"])
+                     and type(method["source_line"]) is int and method["source_line"] > 0,
+                     "invalid method metadata")
+            _require(all(method[key] is None or type(method[key]) is str for key in ("alias_of", "returns")),
+                     "invalid optional method text")
+        for parameters in [entry["parameters"], *(method["parameters"] for method in entry["methods"])]:
+            _require(type(parameters) is list, "API parameters must be arrays")
+            for parameter in parameters:
+                _keys(parameter, "name annotation kind required default", "API parameter")
+                _text(parameter["name"], "parameter name")
+                _require(all(parameter[key] is None or type(parameter[key]) is str
+                             for key in ("annotation", "default")), "invalid parameter type/default")
+                _require(type(parameter["required"]) is bool, "invalid required parameter flag")
+                _require(parameter["kind"] in {"positional_only", "positional_or_keyword", "keyword_only",
+                                               "var_positional", "var_keyword"}, "invalid parameter kind")
+        for field in entry["fields"]:
+            _keys(field, "name annotation default default_factory init keyword_only private", "dataclass field")
+            _text(field["name"], "field name")
+            _text(field["annotation"], "field annotation")
+            _require(all(field[key] is None or type(field[key]) is str for key in ("default", "default_factory")),
+                     "invalid field default")
+            _require(all(type(field[name]) is bool for name in ("init", "keyword_only", "private")),
+                     "invalid dataclass field flags")
+    _require(type(catalog["builtin_backends"]) is list and bool(catalog["builtin_backends"]), "missing built-in metadata")
+    for backend in catalog["builtin_backends"]:
+        _keys(backend, "backend_id version implementation_id capabilities supported_scopes supported_modes suite_ids metadata",
+              "backend declaration")
+        for key in ("backend_id", "version", "implementation_id"):
+            _text(backend[key], "backend " + key)
+        for key in ("capabilities", "supported_scopes", "supported_modes", "suite_ids"):
+            _require(type(backend[key]) is list and bool(backend[key])
+                     and all(type(item) is str and item for item in backend[key]), "invalid backend declarations")
+        _require(type(backend["metadata"]) is dict, "backend metadata must be an object")
+    _require(type(catalog["native_parameter_schemas"]) is dict, "native schemas must be an object")
+    expected_factories = [{key: entry[key] for key in (
+        "id", "target", "signature", "parameters", "summary", "source_path", "source_line")}
+        for entry in catalog["exports"] if entry["kind"] == "function" and entry["returns"] == "WorkflowRegistry"]
+    _require(catalog["registry_factories"] == expected_factories,
+             "configured registry factory metadata differs from public declarations")
+    _keys(catalog["boundaries"], "metadata_only live_hosted_verified catalog_entry_is_execution_admission candidate_source_verified_by_local_builtin",
+          "catalog boundaries")
+    _require(all(type(value) is bool for value in catalog["boundaries"].values()), "capability flags must be boolean")
+    _require(catalog["boundaries"] == {
+        "metadata_only": True, "live_hosted_verified": False,
+        "catalog_entry_is_execution_admission": False, "candidate_source_verified_by_local_builtin": False},
+        "unapproved current capability claim")
+
+
+def check_candidate(source_root, content_path):
+    """Validate current metadata and curated source without a wheel or output."""
+    catalog = extract_catalog(source_root)
+    _validate_catalog(catalog)
+    content = _json(content_path)
+    validate_content(content)
+    _require(content["sdk_version"] == catalog["sdk_version"], "curated/source version mismatch")
+    return {"status": "passed", "candidate_id": content["id"], "sdk_version": catalog["sdk_version"],
+            "export_count": len(catalog["exports"]),
+            "backend_ids": [item["backend_id"] for item in catalog["builtin_backends"]],
+            "catalog_sha256": _sha(_canonical(catalog)), "content_sha256": _sha(_canonical(content))}
+
+
+def _identity(value, *, source_root=None, required=()):
+    _safe_json(value)
+    _keys(value, "schema_version sdk_version distribution source_revision files", "reviewed source identity")
+    _require(value["schema_version"] == "sphynx.release-source.v1", "unsupported reviewed source identity")
+    _text(value["sdk_version"], "source SDK version")
+    _text(value["distribution"], "source distribution")
+    revision = value["source_revision"]
+    _require(type(revision) is str and re.fullmatch(
+        r"git:[0-9a-f]{40,64}\+snapshot:sha256:[0-9a-f]{64}", revision),
+        "source identity must bind a base Git revision plus a reviewed snapshot")
+    _require(type(value["files"]) is list and 1 <= len(value["files"]) <= 5000, "invalid reviewed file inventory")
+    rows, folded = {}, set()
+    for row in value["files"]:
+        _keys(row, "path sha256", "reviewed source row")
+        relative = _relative(row["path"]).as_posix()
+        _require(relative.casefold() not in folded and type(row["sha256"]) is str and _HASH.fullmatch(row["sha256"]),
+                 "duplicate or invalid reviewed source row")
+        rows[relative] = row["sha256"]
+        folded.add(relative.casefold())
+    canonical = "".join(path + "  " + rows[path] + "\n" for path in sorted(rows)).encode("utf-8")
+    _require(revision.rsplit(":", 1)[1] == _sha(canonical), "reviewed snapshot digest mismatch")
+    _require(set(required).issubset(rows), "reviewed source omits a required documentation/runtime input")
+    if source_root is not None:
+        root = Path(source_root).resolve(strict=True)
+        total = 0
+        for relative, digest in rows.items():
+            raw = _read(_source_path(root, relative), MAX_SOURCE_BYTES)
+            total += len(raw)
+            _require(total <= MAX_SOURCE_BYTES, "reviewed source exceeds size limit")
+            _require(_sha(raw) == digest, "stale reviewed source: " + relative)
+        allowlist = _json(_source_path(root, "tools/release/source_allowlist.json"))
+        _require(allowlist.get("schema_version") == "sphynx.release-allowlist.v1"
+                 and allowlist.get("sdk_version") == value["sdk_version"], "source allowlist version mismatch")
+        approved = [item.get("path") for item in allowlist.get("files", []) if isinstance(item, dict)]
+        _require(len(approved) == len(set(approved)) and set(approved) == set(rows),
+                 "source identity must cover the complete reviewed packaging allowlist")
+    return rows
+
+
+def _wheel(wheel, identity, rows):
+    path = Path(wheel)
+    raw = _read(path, MAX_SOURCE_BYTES)
+    expected = {relative.removeprefix("src/"): digest for relative, digest in rows.items()
+                if relative.startswith("src/sphynx/")}
+    distribution, version = identity["distribution"], identity["sdk_version"]
+    normalized = distribution.replace("-", "_")
+    _require(path.name == f"{normalized}-{version}-py3-none-any.whl", "wheel filename/version mismatch")
+    generated = {f"{normalized}-{version}.dist-info/{name}" for name in ("METADATA", "WHEEL", "top_level.txt", "RECORD")}
+    try:
+        with zipfile.ZipFile(path) as archive:
+            infos, folded, runtime = {}, set(), {}
+            total = 0
+            for info in archive.infolist():
+                name = _relative(info.filename).as_posix()
+                _require(not info.is_dir() and name.casefold() not in folded and not info.flag_bits & 1,
+                         "duplicate, encrypted or directory wheel member")
+                _require((info.external_attr >> 16) & 0o170000 != 0o120000, "symlinked wheel member")
+                total += info.file_size
+                _require(total <= MAX_SOURCE_BYTES, "wheel exceeds expanded size limit")
+                infos[name] = info
+                folded.add(name.casefold())
+                if name.startswith("sphynx/"):
+                    runtime[name] = _sha(archive.read(info))
+            _require(runtime == expected, "wheel runtime bytes differ from reviewed source")
+            _require(set(infos) == set(expected) | generated, "wheel has missing or unexpected generated members")
+            metadata_text = archive.read(infos[f"{normalized}-{version}.dist-info/METADATA"]).decode("utf-8")
+            metadata = Parser(policy=policy.default).parsestr(metadata_text, headersonly=True)
+            _require(not metadata.defects
+                     and not any(getattr(header, "defects", ()) for header in metadata.values()),
+                     "malformed wheel package metadata headers")
+            _require([str(value) for value in metadata.get_all("Name", [])] == [distribution]
+                     and [str(value) for value in metadata.get_all("Version", [])] == [version],
+                     "wheel package metadata differs from reviewed identity")
+    except (zipfile.BadZipFile, KeyError, UnicodeError, RuntimeError) as exc:
+        raise CandidateDocumentationError("invalid candidate wheel") from exc
+    return {"filename": path.name, "sha256": _sha(raw), "size_bytes": len(raw)}
+
+
+def _table(columns, rows):
+    e = html.escape
+    return ("<div class='table-wrap'><table><thead><tr>"
+            + "".join("<th>" + e(str(cell)) + "</th>" for cell in columns)
+            + "</tr></thead><tbody>"
+            + "".join("<tr>" + "".join("<td>" + e(str(cell)) + "</td>" for cell in row) + "</tr>" for row in rows)
+            + "</tbody></table></div>")
+
+
+def _parameter_table(rows):
+    return _table(["Parameter", "Type", "Kind", "Default"], [
+        [item["name"], item["annotation"] or "Unannotated", item["kind"],
+         "Required" if item["required"] else item["default"] or "Variadic"] for item in rows])
+
+
+def _render(content, catalog, release):
+    """Produce an offline, escaped summary-to-detail guide with no scripts."""
+    e = html.escape
+    navigation, pages = [], []
+    for page in content["pages"]:
+        navigation.append("<a href='#" + e(page["id"], quote=True) + "'>" + e(page["title"]) + "</a>")
+        sections = []
+        for section in page["sections"]:
+            anchor = page["id"] + "/" + section["id"]
+            parts = ["<section id='" + e(anchor, quote=True) + "'><h3>" + e(section["title"]) + "</h3>"]
+            parts.extend("<p>" + e(paragraph) + "</p>" for paragraph in section["paragraphs"])
+            for block in section["blocks"]:
+                parts.append("<div class='example-label'>" + e(block["language"]) + " · "
+                             + e(block["execution"]) + " example — not executed by the exporter</div><pre><code>"
+                             + e(block["code"]) + "</code></pre>")
+            parts.extend(_table(table["columns"], table["rows"]) for table in section["tables"])
+            parts.extend("<p><a href='" + e(link["url"], quote=True) + "'>" + e(link["label"]) + "</a></p>"
+                         for link in section["links"])
+            parts.append("</section>")
+            sections.append("".join(parts))
+        pages.append("<article id='" + e(page["id"], quote=True) + "'><div class='eyebrow'>"
+                     + e(page["category"]) + "</div><h2>" + e(page["title"]) + "</h2><p class='summary'>"
+                     + e(page["summary"]) + "</p>" + "".join(sections) + "</article>")
+    entries = []
+    for entry in catalog["exports"]:
+        parts = ["<details id='api-" + e(entry["id"], quote=True) + "'><summary><code>"
+                 + e(entry["id"]) + "</code> <span>" + e(entry["kind"]) + "</span></summary>"]
+        parts.append("<p>" + e(entry["summary"]) + "</p><p class='provenance'>Source: "
+                     + e(entry["source_path"]) + ":" + str(entry["source_line"]) + "<br>Target: "
+                     + e(entry["target"]) + "</p>")
+        if entry["alias_of"]:
+            parts.append("<p>Equivalent native target: <code>" + e(entry["target"]) + "</code>.</p>")
+        if entry["signature"]:
+            parts.append("<pre><code>" + e(entry["signature"]) + "</code></pre>")
+        if entry["parameters"]:
+            parts.append(_parameter_table(entry["parameters"]))
+        if entry["fields"]:
+            parts.append("<h4>Declared fields</h4>" + _table(
+                ["Field", "Type", "Default or factory", "Constructor", "Visibility"],
+                [[field["name"], field["annotation"], field["default"] or
+                  ("Factory: " + field["default_factory"] if field["default_factory"] else "Required"),
+                  "Included" if field["init"] else "Excluded", "Internal" if field["private"] else "Public"]
+                 for field in entry["fields"]]))
+        for method in entry["methods"]:
+            parts.append("<details class='method'><summary><code>" + e(method["signature"])
+                         + "</code></summary><p>" + e(method["summary"]) + "</p>"
+                         + ("<p>Decorators: " + e(", ".join(method["decorators"])) + "</p>" if method["decorators"] else "")
+                         + "<p class='provenance'>Target: " + e(method["target"]) + "</p>"
+                         + _parameter_table(method["parameters"]) + "</details>")
+        if entry["kind"] == "constant":
+            parts.append("<pre><code>" + e(json.dumps(entry["value"], ensure_ascii=False, sort_keys=True)) + "</code></pre>")
+        parts.append("</details>")
+        entries.append("".join(parts))
+    backends = _table(["Backend", "Scopes", "Modes", "Native suites"], [
+        [item["backend_id"], ", ".join(item["supported_scopes"]), ", ".join(item["supported_modes"]),
+         ", ".join(item["suite_ids"])] for item in catalog["builtin_backends"]])
+    factories = _table(["Registry factory", "Required configuration", "Source"], [
+        [item["signature"], item["summary"], item["source_path"]]
+        for item in catalog["registry_factories"]])
+    schema_details = "".join("<details><summary>" + e(name) + "</summary><pre><code>"
+                             + e(json.dumps(schema, ensure_ascii=False, indent=2, sort_keys=True)) + "</code></pre></details>"
+                             for name, schema in sorted(catalog["native_parameter_schemas"].items()))
+    style = """
+body{margin:0;background:#f6f8fb;color:#17243b;font:16px/1.6 system-ui,sans-serif}
+header{padding:28px 5%;background:#102746;color:white}header p{max-width:80ch}
+.layout{display:grid;grid-template-columns:240px minmax(0,1050px);gap:32px;max-width:1400px;margin:auto;padding:28px}
+nav{position:sticky;top:20px;align-self:start}nav a{display:block;padding:7px 10px;margin:3px 0}
+a{color:#1761ad}header a{color:#bcdcff}main{min-width:0}article,.panel{background:white;padding:28px;margin:0 0 24px;border:1px solid #dce4ef;border-radius:12px}
+h1,h2,h3,h4{line-height:1.25}h2{margin-top:0}.summary{font-size:18px;color:#465b77}
+.eyebrow,.example-label,.provenance{font-size:13px;color:#526781}.eyebrow{text-transform:uppercase;letter-spacing:.08em}
+pre{white-space:pre-wrap;overflow-wrap:anywhere;padding:18px;border-radius:8px;background:#edf3fa;font-size:13px}
+code{font-family:ui-monospace,Consolas,monospace}details{padding:12px;border:1px solid #dce4ef;border-radius:8px;margin:10px 0}
+summary{cursor:pointer;overflow-wrap:anywhere}summary span{font-size:12px;color:#64748b}.method{margin-left:10px}
+table{border-collapse:collapse;width:100%;font-size:13px}th,td{text-align:left;vertical-align:top;padding:10px;border-bottom:1px solid #dce4ef}
+th{background:#edf3fa}.table-wrap{overflow:auto}.flow{display:flex;gap:6px;flex-wrap:wrap;padding:12px 0}
+.flow span{border:1px solid #a7bedb;border-radius:6px;padding:7px 10px}.badge{display:inline-block;background:#dce9fb;color:#183b68;padding:4px 9px;border-radius:20px;font-size:12px}
+section,article,details{scroll-margin-top:20px}@media(max-width:850px){.layout{grid-template-columns:1fr;padding:16px}nav{position:static;display:flex;flex-wrap:wrap}article,.panel{padding:18px}}
+"""
+    head = ("<!doctype html><html lang='en'><head><meta charset='utf-8'>"
+            "<meta name='viewport' content='width=device-width,initial-scale=1'>"
+            "<meta http-equiv='Content-Security-Policy' content=\"default-src 'none'; style-src 'unsafe-inline'; img-src 'none'; base-uri 'none'; form-action 'none'\">"
+            "<title>Sphynx " + e(content["sdk_version"]) + " review documentation</title><style>" + style + "</style></head><body>")
+    header = ("<header><span class='badge'>Unpublished review candidate</span><h1>Sphynx engineering evaluations</h1>"
+              "<p>Define a suite. Plan a candidate run. Retain evidence. Assess it and compare compatible reports.</p>"
+              "<p>" + e(content["id"]) + " · SDK " + e(content["sdk_version"]) + "</p></header>")
+    overview = ("<section class='panel'><h2>One workflow, explicit domain behavior</h2><div class='flow' aria-label='Workflow overview'>"
+                + " → ".join("<span>" + label + "</span>" for label in
+                              ("Suite", "Plan", "Resolve", "Admit", "Run", "Assess", "Report", "Compare"))
+                + "</div><p>The backend owns domain payloads, evidence verification and comparison policies. "
+                "Completion is not a quality verdict. Local source metadata does not verify a PR revision.</p></section>")
+    api = ("<article id='generated-api'><h2>Generated API reference</h2><p>Extracted by AST from the reviewed source. "
+           "Signatures retain source annotations/default expressions. Dataclass factories are identified explicitly. "
+           "No provider, candidate, evaluator or example ran during export.</p>" + "".join(entries) + "</article>")
+    capabilities = ("<article id='generated-capabilities'><h2>Workflow libraries</h2><h3>Default bindings</h3>" + backends
+                    + "<h3>Configured registry factories</h3><p>These public factories are derived from source declarations. "
+                    "Supply their operator configuration, then inspect the registered backend descriptor. "
+                    "Discovery does not grant asset access or verify a live deployment.</p>" + factories
+                    + "<p>Native library catalog entries do not imply a common backend. The default local adapter "
+                    "does not verify candidate source bytes or provide OS isolation.</p><h3>Native parameter schemas</h3>"
+                    "<p>These existing native contracts remain domain-specific. A schema declaration is not execution admission.</p>"
+                    + schema_details + "</article>")
+    receipt = ("<article id='candidate-receipt'><h2>Candidate provenance</h2>"
+               + _table(["Field", "Value"], [
+                   ["Package", release["distribution"] + " " + release["sdk_version"]],
+                   ["Wheel SHA256", release["wheel"]["sha256"]],
+                   ["Source revision", release["source_revision"]],
+                   ["Base commit contains all reviewed source", "No; the snapshot digest identifies changed source"],
+                   ["Delivery", "Review only; not published or deployed"]])
+               + "<p><a href='bundle.json'>Approved bundle identity</a> · <a href='manifest.json'>File checksums</a> · "
+               "<a href='source-identity.json'>Reviewed source inventory</a> · <a href='catalog.json'>Generated catalog</a></p></article>")
+    nav = "".join(navigation) + "<a href='#generated-api'>API reference</a><a href='#generated-capabilities'>Capabilities</a><a href='#candidate-receipt'>Provenance</a>"
+    raw = (head + header + "<div class='layout'><nav aria-label='Guide navigation'>" + nav
+           + "</nav><main>" + overview + "".join(pages) + api + capabilities + receipt + "</main></div></body></html>").encode("utf-8")
+    _require(len(raw) <= MAX_JSON_BYTES, "rendered candidate exceeds size limit")
+    return raw
+
+
+def export_candidate(source_root, content_path, wheel, source_identity, output):
+    """Bind guides/catalog/HTML to actual wheel and reviewed source bytes."""
+    root = Path(source_root).resolve(strict=True)
+    content_path = Path(content_path).resolve(strict=True)
+    _require(content_path.is_relative_to(root), "curated source must be in the reviewed source root")
+    catalog, content = extract_catalog(root), _json(content_path)
+    _validate_catalog(catalog)
+    validate_content(content)
+    identity = _json(source_identity)
+    required = {*_CORE_SOURCE, content_path.relative_to(root).as_posix(),
+                *(entry["source_path"] for entry in catalog["exports"])}
+    rows = _identity(identity, source_root=root, required=required)
+    _require(content["sdk_version"] == catalog["sdk_version"] == identity["sdk_version"],
+             "candidate content/source/package version mismatch")
+    _require(identity["distribution"] == catalog["distribution"], "candidate distribution mismatch")
+    wheel_identity = _wheel(wheel, identity, rows)
+    release = {"id": content["id"], "sdk_version": catalog["sdk_version"],
+               "distribution": catalog["distribution"], "source_revision": identity["source_revision"],
+               "base_head_contains_all_reviewed_source": False, "wheel": wheel_identity,
+               "content_source_path": content_path.relative_to(root).as_posix()}
+    files = {"catalog.json": _canonical(catalog), "content.json": _canonical(content),
+             "source-identity.json": _canonical(identity), "index.html": _render(content, catalog, release)}
+    bundle = {"schema_version": BUNDLE_SCHEMA, "exporter_version": EXPORTER_VERSION,
+              "release": release, "files": {
+                  name: {"sha256": _sha(raw), "size_bytes": len(raw)} for name, raw in sorted(files.items())}}
+    files["bundle.json"] = _canonical(bundle)
+    manifest = {"schema_version": MANIFEST_SCHEMA, "bundle_sha256": _sha(files["bundle.json"]),
+                "files": {name: {"sha256": _sha(raw), "size_bytes": len(raw)} for name, raw in sorted(files.items())}}
+    files["manifest.json"] = _canonical(manifest)
+    destination = Path(output)
+    _require(not destination.is_symlink(), "candidate output must not be symlinked")
+    if destination.exists():
+        _require(destination.is_dir() and {item.name for item in destination.iterdir()} == _MEMBERS,
+                 "existing candidate output differs; choose a new directory")
+        _require(all(_read(destination / name) == raw for name, raw in files.items()),
+                 "existing candidate bytes differ; choose a new directory")
+    else:
+        destination.mkdir(parents=True)
+        for name, raw in files.items():
+            with (destination / name).open("xb") as stream:
+                stream.write(raw)
+    return verify_candidate(destination, manifest["bundle_sha256"], source_root=root, wheel=wheel)
+
+
+def verify_candidate(bundle_dir, expected_sha256, *, source_root=None, wheel=None):
+    """Verify an approved bundle digest and optional current source/wheel bytes."""
+    _require(type(expected_sha256) is str and _HASH.fullmatch(expected_sha256),
+             "verification requires an approved bundle.json SHA256")
+    _require(not Path(bundle_dir).is_symlink(), "candidate bundle directory must not be symlinked")
+    directory = Path(bundle_dir).resolve(strict=True)
+    _require({item.name for item in directory.iterdir()} == _MEMBERS, "candidate bundle has missing or extra files")
+    bundle_raw = _read(directory / "bundle.json")
+    _require(_sha(bundle_raw) == expected_sha256, "approved candidate bundle digest mismatch")
+    bundle, manifest = _json(directory / "bundle.json"), _json(directory / "manifest.json")
+    _keys(bundle, "schema_version exporter_version release files", "candidate bundle")
+    _require(bundle["schema_version"] == BUNDLE_SCHEMA and bundle["exporter_version"] == EXPORTER_VERSION,
+             "unsupported candidate bundle/exporter version")
+    _keys(manifest, "schema_version bundle_sha256 files", "candidate manifest")
+    _require(manifest["schema_version"] == MANIFEST_SCHEMA and manifest["bundle_sha256"] == expected_sha256,
+             "candidate manifest identity mismatch")
+    _require(type(bundle["files"]) is dict and set(bundle["files"]) == set(_FILES), "unapproved candidate file set")
+    expected_files = dict(bundle["files"])
+    expected_files["bundle.json"] = {"sha256": expected_sha256, "size_bytes": len(bundle_raw)}
+    _require(manifest["files"] == expected_files, "manifest differs from approved bundle checksums")
+    for name, row in expected_files.items():
+        _keys(row, "sha256 size_bytes", "file receipt")
+        _require(type(row["sha256"]) is str and _HASH.fullmatch(row["sha256"])
+                 and type(row["size_bytes"]) is int and 0 <= row["size_bytes"] <= MAX_JSON_BYTES, "invalid file receipt")
+        raw = _read(directory / name)
+        _require(len(raw) == row["size_bytes"] and _sha(raw) == row["sha256"], "candidate file digest mismatch: " + name)
+    content, catalog, identity = (_json(directory / name) for name in ("content.json", "catalog.json", "source-identity.json"))
+    validate_content(content)
+    _validate_catalog(catalog)
+    release = bundle["release"]
+    _keys(release, "id sdk_version distribution source_revision base_head_contains_all_reviewed_source wheel content_source_path",
+          "candidate release")
+    content_source = _relative(release["content_source_path"]).as_posix()
+    rows = _identity(identity, source_root=source_root,
+                     required={*_CORE_SOURCE, content_source, *(entry["source_path"] for entry in catalog["exports"])})
+    _keys(release["wheel"], "filename sha256 size_bytes", "wheel receipt")
+    _relative(release["wheel"]["filename"])
+    _require(type(release["wheel"]["sha256"]) is str and _HASH.fullmatch(release["wheel"]["sha256"])
+             and type(release["wheel"]["size_bytes"]) is int
+             and 0 < release["wheel"]["size_bytes"] <= MAX_SOURCE_BYTES, "invalid wheel receipt")
+    _require(release["id"] == content["id"] and release["sdk_version"] == content["sdk_version"]
+             == catalog["sdk_version"] == identity["sdk_version"], "candidate SDK/content identity mismatch")
+    _require(release["source_revision"] == identity["source_revision"]
+             and release["distribution"] == catalog["distribution"] == identity["distribution"]
+             and release["base_head_contains_all_reviewed_source"] is False, "candidate source identity mismatch")
+    if source_root is not None:
+        _require(extract_catalog(source_root) == catalog, "stale candidate API/catalog metadata")
+        _require(_json(_source_path(Path(source_root).resolve(strict=True), content_source)) == content,
+                 "candidate guides differ from their reviewed source")
+    if wheel is not None:
+        _require(_wheel(wheel, identity, rows) == release["wheel"], "candidate wheel differs from approved receipt")
+    _require(_render(content, catalog, release) == _read(directory / "index.html"), "candidate HTML differs from approved rendering")
+    return {"status": "passed", "candidate_id": release["id"], "sdk_version": release["sdk_version"],
+            "bundle_sha256": expected_sha256, "source_revision": release["source_revision"],
+            "wheel_sha256": release["wheel"]["sha256"], "source_file_count": len(rows),
+            "export_count": len(catalog["exports"]), "source_checked": source_root is not None,
+            "wheel_checked": wheel is not None}
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__)
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    root_default = Path(__file__).resolve().parents[2]
+    check = subparsers.add_parser("candidate-check", help="Validate source declarations and curated guides only")
+    check.add_argument("--source-root", type=Path, default=root_default)
+    check.add_argument("--content", type=Path, required=True)
+    export = subparsers.add_parser("candidate-export", help="Bind a review bundle to actual reviewed source and wheel")
+    for name in ("source-root", "content", "wheel", "source-identity", "output"):
+        export.add_argument("--" + name, type=Path, required=True)
+    verify = subparsers.add_parser("candidate-verify", help="Verify the approved bundle digest and optional source/wheel")
+    verify.add_argument("--bundle-dir", type=Path, required=True)
+    verify.add_argument("--expected-sha256", required=True)
+    verify.add_argument("--source-root", type=Path)
+    verify.add_argument("--wheel", type=Path)
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "candidate-check":
+            result = check_candidate(args.source_root, args.content)
+        elif args.command == "candidate-export":
+            result = export_candidate(args.source_root, args.content, args.wheel, args.source_identity, args.output)
+        else:
+            result = verify_candidate(args.bundle_dir, args.expected_sha256, source_root=args.source_root, wheel=args.wheel)
+    except (CandidateDocumentationError, OSError, KeyError, TypeError) as exc:
+        parser.exit(2, "candidate documentation: " + str(exc) + "\n")
+    print(json.dumps(result, ensure_ascii=True, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())