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

sphynx/documentation.py

@@ -0,0 +1,737 @@
+"""Versioned, metadata-only documentation exports.
+
+This module uses Python's AST, never imports the inspected SDK, and never runs
+examples, candidate code, providers, models, or evaluation adapters.
+"""
+from __future__ import annotations
+
+import argparse
+import ast
+import copy
+import hashlib
+import json
+import re
+import sys
+import tomllib
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+EXPORTER_VERSION = "1.4.0"
+SUPPORTED_EXPORTER_VERSIONS = {"1.0.0", "1.1.0", "1.2.0", "1.3.0", EXPORTER_VERSION}
+SOURCE_RECEIPTS_FORMAT = "utf8-lf.v1"
+MAX_BUNDLE_BYTES = 2_000_000
+SCHEMA = "sphynx.docs.bundle.v1"
+MANIFEST_SCHEMA = "sphynx.docs.manifest.v1"
+IMPLEMENTED_IDS = {
+    "rag.rerank.v1", "rag.rerank.public.v1", "rag.rerank.sable.dev.v1",
+    "rag.rerank.beir.v1", "rag.invoke.v1", "rag.retrieve.v1",
+    "rag.question_robustness.v1", "rag.chunk.v1", "rag.pipeline.v1", "rag.full_rag.v1",
+}
+CONTRACT_IDS = {"rag.rerank.v2", "audio.similarity.v1"}
+HOSTED_IDS = {"rag.rerank.v1", "rag.rerank.public.v1"}
+API_MODULES = {
+    "client": ["Client.__init__", "Client.evaluate", "Client.list_evals", "Client.describe_eval", "Client.list_benchmarks", "Client.get_benchmark", "Client.get_label_release", "Client.get_experiment", "Client.get_run", "Client.grade", "Client.get_evaluation", "Client.compare_saved", "Client.get_comparison", "Client.leaderboard", "Experiment.wait", "Experiment.refresh", "HostedRun.grade", "HostedEvaluation.wait", "ComparisonRef.result"],
+    "packs": ["list_packs", "get_pack", "check_candidate"],
+    "evals": ["list_evals", "describe_eval", "resolve_eval"],
+    "catalog": ["list_datasets", "get_dataset", "list_candidates"],
+    "runner": ["run"], "results": ["grade", "report", "compare"],
+    "demo": ["run_demo"],
+    "public_rerank": ["run_public_rerank", "grade_public_rerank", "report_public_rerank", "compare_public_rerank"],
+    "sable_rerank": ["run_private_rerank", "grade_private_rerank", "compare_private_rerank"],
+    "invocation": ["list_invocation_banks", "load_invocation_pack", "run_invocation", "grade_invocation", "report_invocation", "compare_invocation"],
+    "retrieval": ["load_retrieval_pack", "run_retrieval", "capture_retrieval", "grade_retrieval", "compare_retrieval"],
+    "question_robustness": ["run_question_robustness", "grade_question_robustness", "report_question_robustness", "compare_question_robustness"],
+    "chunking": ["run_chunking", "grade_chunking", "report_chunking", "compare_chunking"],
+    "pipeline": ["run_pipeline", "grade_pipeline", "report_pipeline", "compare_pipeline"],
+    "full_rag": ["run_full_rag", "grade_full_rag", "report_full_rag", "compare_full_rag", "compare_full_rag_contexts", "create_full_rag_review_template"],
+    "score_reliability": ["grade_score_reliability", "compare_score_reliability", "evaluate_fitted_calibrator", "report_fitted_calibrator"],
+    "reviewer_audit": ["audit_invocation_reviewer"],
+    "workbench_tracks": ["run_workbench_pipeline", "run_workbench_full_rag"],
+}
+LEGACY_SOURCE_FILES = sorted({"pyproject.toml", "src/sphynx/__init__.py", "src/sphynx/public_eval.py", *(f"src/sphynx/{name}.py" for name in API_MODULES)})
+PREVIOUS_SOURCE_FILES = sorted(set(LEGACY_SOURCE_FILES) | {"src/sphynx/rag_diagnostics.py", *("src/sphynx/_rag_diagnostics_" + name + ".py" for name in ("common", "contracts", "ranking", "semantic", "engine", "catalog", "calibration", "importers"))})
+# Additive SDK 0.5.0 APIs; explicit namespaces prevent false root exports.
+API_MODULES.update({'rag_papers/contracts': ['make_case', 'make_trace', 'judgment', 'candidate_input', 'validate_case', 'validate_trace', 'validate_judgment'], 'rag_papers/datasets': ['prepare_paper_dataset', 'prepare_official_paper_dataset', 'prepare_canonical_paper_dataset', 'load_paper_dataset', 'PaperDataset.cases'], 'rag_papers/registry': ['describe_paper_methods'], 'rag_papers/scoring': ['evaluate_beir', 'evaluate_hotpotqa', 'evaluate_musique', 'evaluate_qasper', 'evaluate_rgb', 'evaluate_crag'], 'rag_papers/semantic': ['evaluate_sufficient_context', 'evaluate_ragas', 'evaluate_alce', 'evaluate_ares', 'evaluate_factscore', 'evaluate_ragchecker', 'evaluate_lost_in_the_middle', 'evaluate_trec_rag_2025'], 'rag_papers/judges': ['JsonJudgeAdapter.__init__', 'JudgeSession.__init__', 'run_paper_judge', 'prepare_ares_training', 'train_ares_judge'], 'rag_papers/candidates': ['candidate_trace'], 'rag_papers/runner': ['capture_paper_candidate', 'run_paper_suite', 'load_paper_run', 'compare_paper_runs'], 'rag_papers/experiments': ['plan_lost_in_the_middle', 'plan_rgb', 'plan_musique', 'prepare_intervention_dataset'], 'rag_papers/sable': ['prepare_sable_paper_dataset', 'evaluate_sable_evidence', 'bind_reflex_case_history', 'trace_from_level3', 'trace_from_full_rag_capture'], 'rag_papers/schemas': ['get_paper_schema'], 'rag_papers/trec': ['prepare_trec_rag_2025_dataset', 'trace_from_trec_rag_2025'], 'reflex_traces': ['load_reflex_traces', 'pair_reflex_traces'], 'official_benchmarks': ['list_official_benchmarks', 'fetch_official_benchmark_source', 'prepare_official_benchmark', 'load_official_benchmark'], 'speech_contracts': ['require', 'encode', 'sha', 'parse', 'fields', 'identifier', 'checksum', 'validate_method', 'validate_request', 'decode_audio', 'serve_tts'], 'speech_evidence': ['import_kido_speech_evidence', 'load_speech_evidence', 'describe_speech_suite', 'speech_candidate_view', 'grade_speech_evidence', 'load_speech_evaluation'], 'speech_tts': ['describe_tts_suite', 'freeze_tts_plan', 'run_tts_plan', 'grade_tts_captures', 'load_tts_run']})
+PUBLIC_API_NAMESPACES = {'rag_papers/contracts': 'sphynx.rag_papers', 'rag_papers/datasets': 'sphynx.rag_papers', 'rag_papers/registry': 'sphynx.rag_papers', 'rag_papers/scoring': 'sphynx.rag_papers', 'rag_papers/semantic': 'sphynx.rag_papers', 'rag_papers/judges': 'sphynx.rag_papers', 'rag_papers/candidates': 'sphynx.rag_papers', 'rag_papers/runner': 'sphynx.rag_papers', 'rag_papers/experiments': 'sphynx.rag_papers', 'rag_papers/sable': 'sphynx.rag_papers', 'rag_papers/schemas': 'sphynx.rag_papers', 'rag_papers/trec': 'sphynx.rag_papers', 'reflex_traces': 'sphynx.reflex_traces', 'official_benchmarks': 'sphynx.official_benchmarks', 'speech_contracts': 'sphynx.speech_contracts', 'speech_evidence': 'sphynx.speech_evidence', 'speech_tts': 'sphynx.speech_tts'}
+SOURCE_FILES = sorted({"pyproject.toml", "src/sphynx/__init__.py", "src/sphynx/public_eval.py", *(f"src/sphynx/{name}.py" for name in API_MODULES)})
+API_MODULES["rag_diagnostics"] = ['load_rag_diagnostics_dataset', 'validate_rag_diagnostics_dataset', 'rag_candidate_view', 'grade_rag_diagnostics', 'load_rag_diagnostics_demo', 'list_rag_diagnostics_metrics', 'rag_diagnostics_capabilities', 'save_rag_diagnostics_report', 'load_rag_diagnostics_report', 'render_rag_diagnostics_report', 'import_rag_diagnostics_beir', 'audit_rag_judge', 'estimate_rag_ppi_mean', 'create_rag_diagnostics_review_template']
+SOURCE_FILES = sorted({"pyproject.toml", "src/sphynx/__init__.py", "src/sphynx/public_eval.py", *(f"src/sphynx/{name}.py" for name in API_MODULES)})
+SOURCE_FILES = sorted(SOURCE_FILES + ['src/sphynx/_rag_diagnostics_common.py', 'src/sphynx/_rag_diagnostics_contracts.py', 'src/sphynx/_rag_diagnostics_ranking.py', 'src/sphynx/_rag_diagnostics_semantic.py', 'src/sphynx/_rag_diagnostics_engine.py', 'src/sphynx/_rag_diagnostics_catalog.py', 'src/sphynx/_rag_diagnostics_calibration.py', 'src/sphynx/_rag_diagnostics_importers.py'])
+KEYS = {
+    "payload": "schema_version release pages suites api families methods datasets controls evidence versions known_gaps reconciliation references".split(),
+    "manifest": "schema_version content_sha256 content_bytes catalog_sha256 source_receipts source_receipts_format source_receipts_sha256 build_time_utc exporter_sha256 references_sha256 documentation_source_receipts documentation_source_receipts_sha256".split(),
+    "release": "id label sdk_version source_commit source_tree source_repository wheel_sha256 exporter_version hosted_capability".split(),
+    "capability": "observed_on identity hosted_suite_ids".split(),
+    "page": "id title category summary sections".split(),
+    "section": "id title paragraphs blocks tables links".split(),
+    "block": "language code execution".split(), "table": ["columns", "rows"], "link": ["label", "url"],
+    "suite": "id title status local_api hosted_admitted boundary data_requirements label_authority metrics api_ids known_gaps source_url parameters examples returns failures evidence_ids".split(),
+    "metric": ["id", "denominator"],
+    "suite_parameter": "name type required default accepted description".split(),
+    "api": "id module signature parameters returns summary source_url".split(),
+    "api_parameter": "name type kind required default description accepted".split(),
+    "family": "id title pr_url head_sha source_url entry_count payload_sha256 source_inventory_sha256 hosted_admitted hosted_root superseded".split(),
+    "hosted_root": "method runtime_profile threads suite baseline admitted fresh_execution_verified".split(),
+    "superseded": "pr_url head_sha source_url".split(),
+    "method": "id family name algorithm aliases execution_modes status pr_url head_sha source_url parameters prerequisites known_gaps model configuration_digest hosted_admitted supported_evaluations".split(),
+    "model": "checkpoint revision tokenizer_revision backend device threads max_length batch_size activation truncation seed".split(),
+    "dataset": "id suite_id release population split case_count source_case_count review_status status reason previously_exercised access_requirements source_url".split(),
+    "control": "id title methods pr_url head_sha source_url status".split(),
+    "evidence": "id title type status summary counts source_url source_commit limitations experiment_id run_id evaluation_id requires_ownership metrics runtime".split(),
+    "version": "id title summary source_url".split(),
+    "reconciliation": "discovery suite_ids missing_suite_ids explanation".split(),
+    "references": "families methods concepts".split(),
+    "reference_family": "id title summary purpose changes notes".split(),
+    "reference_method": "id title summary purpose canonical_id steps equations configuration differences notes".split(),
+    "reference_concept": "id title summary paragraphs equations".split(),
+    "equation": "latex explanation symbols".split(),
+    "equation_symbol": "symbol description".split(),
+    "reference_configuration": "name value description".split(),
+}
+FORBIDDEN_KEY = re.compile(r"^(?:token|password|secret|credential|raw_questions?|raw_labels?|answer_capture|weights?|fitted_state|gcs_uri|internal_path|environment)$", re.I)
+FORBIDDEN_TEXT = re.compile(r"(?:gs://|[A-Za-z]:[\\/](?:Users|ProgramData)[\\/]|(?:^|[\\/])\.agent[\\/]|<\s*(?:script|iframe|object|svg)\b|javascript:|-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----|sk-[A-Za-z0-9]{20,})", re.I)
+
+
+class DocumentationError(ValueError):
+    """Invalid, stale, incompatible, or unapproved documentation metadata."""
+
+
+def canonical_bytes(value: Any) -> bytes:
+    return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"), allow_nan=False).encode("utf-8")
+
+
+def sha256(value: bytes) -> str:
+    return hashlib.sha256(value).hexdigest()
+
+
+def _keys(value: Any, kind: str, *, optional: tuple[str, ...] = ()) -> None:
+    if not isinstance(value, dict):
+        raise DocumentationError(f"{kind} must be an object")
+    allowed = set(KEYS[kind])
+    missing = allowed - set(value) - set(optional)
+    unknown = set(value) - allowed
+    if missing or unknown:
+        raise DocumentationError(f"{kind} keys: missing={sorted(missing)}, unapproved={sorted(unknown)}")
+
+
+def _hash(value: Any, name: str, length: int = 64) -> None:
+    if not isinstance(value, str) or not re.fullmatch(rf"[0-9a-f]{{{length}}}", value):
+        raise DocumentationError(f"{name} must be a complete {length}-character lowercase hash")
+
+
+def _strings(value: Any, name: str) -> None:
+    if not isinstance(value, list) or any(not isinstance(item, str) for item in value):
+        raise DocumentationError(f"{name} must be an array of strings")
+
+
+def _confidentiality(value: Any, path: str = "payload") -> None:
+    if isinstance(value, dict):
+        for key, item in value.items():
+            if FORBIDDEN_KEY.fullmatch(key):
+                raise DocumentationError(f"unapproved internal field: {path}.{key}")
+            _confidentiality(item, f"{path}.{key}")
+    elif isinstance(value, list):
+        for index, item in enumerate(value):
+            _confidentiality(item, f"{path}[{index}]")
+    elif isinstance(value, str) and FORBIDDEN_TEXT.search(value):
+        raise DocumentationError(f"unapproved private locator or executable content in {path}")
+
+
+def _unique(items: Any, name: str, key: str = "id") -> set[str]:
+    if not isinstance(items, list):
+        raise DocumentationError(f"{name} must be an array")
+    ids = [item.get(key) if isinstance(item, dict) else None for item in items]
+    if any(not isinstance(item, str) or not item or len(item) > 256 for item in ids) or len(ids) != len(set(ids)):
+        raise DocumentationError(f"{name} has missing/invalid/duplicate IDs")
+    return set(ids)
+
+
+def _url(value: Any) -> None:
+    if not isinstance(value, str) or not re.match(r"^https://(?:github\.com/sable-inc/|huggingface\.co/docs/|docs\.pytorch\.org/)", value):
+        raise DocumentationError("source/link URL must use an approved HTTPS source")
+
+
+def _guide_link(value: Any, pages: dict) -> None:
+    if isinstance(value, str) and value.startswith("#"):
+        match = re.fullmatch(r"#([a-zA-Z0-9._-]+)(?:/([a-zA-Z0-9._-]+))?", value)
+        target = pages.get(match[1]) if match else None
+        if target is None or (match[2] and not any(section["id"] == match[2] for section in target["sections"])):
+            raise DocumentationError("internal guide link must identify an existing page and section")
+    else:
+        _url(value)
+
+
+def _block(value: Any) -> None:
+    _keys(value, "block")
+    if value["language"] not in {"python", "powershell", "bash", "text"} or value["execution"] not in {"fixture", "read_only", "paid_remote", "metadata_only"}:
+        raise DocumentationError("unknown example language/execution boundary")
+    if not isinstance(value["code"], str) or value["code"].startswith((">>>", "PS ", "$ ")):
+        raise DocumentationError("copyable examples must contain code without prompts")
+    if value["language"] == "python":
+        try:
+            ast.parse(value["code"])
+        except SyntaxError as error:
+            raise DocumentationError(f"example syntax: {error.msg}") from error
+
+
+def _text(value: Any, name: str) -> None:
+    if not isinstance(value, str) or not value.strip() or len(value) > 20_000:
+        raise DocumentationError(f"{name} must be a nonempty bounded string")
+
+
+def _equations(values: Any) -> None:
+    if not isinstance(values, list):
+        raise DocumentationError("equations must be an array")
+    for equation in values:
+        _keys(equation, "equation")
+        _text(equation["latex"], "equation LaTeX")
+        _text(equation["explanation"], "equation explanation")
+        _unique(equation["symbols"], "equation symbols", "symbol")
+        for symbol in equation["symbols"]:
+            _keys(symbol, "equation_symbol")
+            _text(symbol["description"], "symbol description")
+
+
+def validate_references(references: Any, payload: dict[str, Any]) -> None:
+    """Check explanatory coverage while retaining exact historical selectors."""
+    _keys(references, "references")
+    _confidentiality(references, "references")
+    families = _unique(references["families"], "reference families")
+    methods = _unique(references["methods"], "reference methods")
+    _unique(references["concepts"], "reference concepts")
+    if families != {item["id"] for item in payload["families"]} or methods != {item["id"] for item in payload["methods"]}:
+        raise DocumentationError("reference coverage must retain every catalog family and method ID")
+    method_families = {item["id"]: item["family"] for item in payload["methods"]}
+    reference_methods = {item["id"]: item for item in references["methods"]}
+    for item in references["methods"]:
+        _keys(item, "reference_method")
+    for kind, collection in (("reference_family", "families"), ("reference_method", "methods"), ("reference_concept", "concepts")):
+        for item in references[collection]:
+            _keys(item, kind)
+            for field in ("title", "summary"):
+                _text(item[field], f"{kind} {field}")
+            if collection != "concepts":
+                _text(item["purpose"], f"{kind} purpose")
+            for field in ("changes", "notes", "steps", "differences", "paragraphs"):
+                if field in item:
+                    _strings(item[field], f"{kind} {field}")
+                    for value in item[field]:
+                        _text(value, f"{kind} {field}")
+            if "equations" in item:
+                _equations(item["equations"])
+            if collection == "methods":
+                canonical = item["canonical_id"]
+                if not isinstance(canonical, str) or canonical not in methods or method_families[canonical] != method_families[item["id"]]:
+                    raise DocumentationError("canonical method must be an existing ID in the same family")
+                if reference_methods[canonical]["canonical_id"] != canonical:
+                    raise DocumentationError("canonical method must resolve directly to a canonical record")
+                _unique(item["configuration"], "reference configuration", "name")
+                for parameter in item["configuration"]:
+                    _keys(parameter, "reference_configuration")
+                    _text(parameter["value"], "configuration value")
+                    _text(parameter["description"], "configuration description")
+
+
+def validate_payload(payload: dict[str, Any]) -> None:
+    """Validate the narrow public contract, identity, references, and status fixtures."""
+    _keys(payload, "payload", optional=("references",))
+    if payload["schema_version"] != SCHEMA:
+        raise DocumentationError("unsupported documentation schema")
+    if len(canonical_bytes(payload)) > MAX_BUNDLE_BYTES:
+        raise DocumentationError("documentation payload exceeds size limit")
+    _confidentiality(payload)
+    release = payload["release"]
+    _keys(release, "release")
+    if not isinstance(release["id"], str) or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]{0,127}", release["id"]):
+        raise DocumentationError("release ID must be a stable bounded identifier")
+    _hash(release["source_commit"], "source commit", 40)
+    _hash(release["source_tree"], "source tree", 40)
+    _hash(release["wheel_sha256"], "wheel digest")
+    if release["source_repository"] != "https://github.com/sable-inc/sphynx" or release["exporter_version"] not in SUPPORTED_EXPORTER_VERSIONS:
+        raise DocumentationError("incompatible documentation source/exporter")
+    _keys(release["hosted_capability"], "capability")
+    capability = release["hosted_capability"]
+    if not isinstance(capability["observed_on"], str) or not re.fullmatch(r"\d{4}-\d{2}-\d{2}", capability["observed_on"]) or not isinstance(capability["identity"], str):
+        raise DocumentationError("hosted capability needs an explicit observation date and identity")
+    _strings(capability["hosted_suite_ids"], "hosted suite IDs")
+    if set(release["hosted_capability"]["hosted_suite_ids"]) != HOSTED_IDS:
+        raise DocumentationError("hosted availability must describe exactly the two admitted suites")
+    ids = {name: _unique(payload[name], name) for name in ("pages", "suites", "api", "families", "methods", "datasets", "controls", "evidence", "versions")}
+    if ids["suites"] != IMPLEMENTED_IDS | CONTRACT_IDS:
+        raise DocumentationError("suite inventory must reconcile all ten implemented and two contract-only IDs")
+    if len(payload["methods"]) != 85 or {f["id"]: f["entry_count"] for f in payload["families"]} != {"statistical": 50, "learned": 9, "pointwise": 5, "invocation": 14, "retrieval": 7}:
+        raise DocumentationError("research catalogue must retain 85 entries across five families; entries are not fresh models")
+    page_map = {page["id"]: page for page in payload["pages"]}
+    for page in payload["pages"]:
+        _keys(page, "page")
+        _unique(page["sections"], "page sections")
+        for section in page["sections"]:
+            _keys(section, "section")
+            if not all(isinstance(p, str) for p in section["paragraphs"]):
+                raise DocumentationError("paragraphs must be plain strings")
+            for block in section["blocks"]:
+                _block(block)
+            for table in section["tables"]:
+                _keys(table, "table")
+                _strings(table["columns"], "table columns")
+                for row in table["rows"]:
+                    _strings(row, "table row")
+                if not table["columns"] or any(len(row) != len(table["columns"]) for row in table["rows"]):
+                    raise DocumentationError("table rows must match column count")
+            for link in section["links"]:
+                _keys(link, "link")
+                _guide_link(link["url"], page_map)
+    for suite in payload["suites"]:
+        _keys(suite, "suite")
+        for field in ("data_requirements", "api_ids", "known_gaps", "returns", "failures", "evidence_ids"):
+            _strings(suite[field], f"suite {field}")
+        if type(suite["local_api"]) is not bool or type(suite["hosted_admitted"]) is not bool:
+            raise DocumentationError("suite availability requires explicit booleans")
+        expected_status = "implemented" if suite["id"] in IMPLEMENTED_IDS else "contract_only"
+        if suite["status"] != expected_status or suite["hosted_admitted"] != (suite["id"] in HOSTED_IDS) or (suite["id"] in CONTRACT_IDS and suite["local_api"]):
+            raise DocumentationError(f"suite status/admission regression: {suite['id']}")
+        if not set(suite["api_ids"]) <= ids["api"] or not set(suite["evidence_ids"]) <= ids["evidence"]:
+            raise DocumentationError(f"missing API/evidence reference: {suite['id']}")
+        _url(suite["source_url"])
+        for metric in suite["metrics"]:
+            _keys(metric, "metric")
+        for parameter in suite["parameters"]:
+            _keys(parameter, "suite_parameter")
+            _strings(parameter["accepted"], "suite accepted values")
+        for example in suite["examples"]:
+            _block(example)
+    for interface in payload["api"]:
+        _keys(interface, "api")
+        _url(interface["source_url"])
+        names = set()
+        for parameter in interface["parameters"]:
+            _keys(parameter, "api_parameter")
+            _strings(parameter["accepted"], "API accepted values")
+            if parameter["name"] in names:
+                raise DocumentationError("duplicate API parameter")
+            names.add(parameter["name"])
+    for family in payload["families"]:
+        _keys(family, "family")
+        _hash(family["head_sha"], "family head", 40)
+        _url(family["source_url"])
+        _keys(family["superseded"], "superseded")
+        if family["hosted_root"] is not None:
+            _keys(family["hosted_root"], "hosted_root")
+        if family["hosted_admitted"] is not False:
+            raise DocumentationError("research factory metadata is not family hosted admission")
+        if sum(method["family"] == family["id"] for method in payload["methods"]) != family["entry_count"]:
+            raise DocumentationError("family entry count does not match exact method inventory")
+    family_map = {family["id"]: family for family in payload["families"]}
+    for method in payload["methods"]:
+        _keys(method, "method")
+        if method["family"] not in ids["families"] or not set(method["supported_evaluations"]) <= ids["suites"]:
+            raise DocumentationError("method has missing family/evaluation reference")
+        _hash(method["head_sha"], "method head", 40)
+        family = family_map[method["family"]]
+        if method["head_sha"] != family["head_sha"] or method["pr_url"] != family["pr_url"]:
+            raise DocumentationError("method identity does not match its frozen family observation")
+        for field in ("aliases", "execution_modes", "prerequisites", "known_gaps", "supported_evaluations"):
+            _strings(method[field], f"method {field}")
+        _url(method["source_url"])
+        if method["hosted_admitted"] is not False:
+            raise DocumentationError("research method profiles are not the separately admitted hosted root")
+        if method["name"] in {"aidan-production", "aidan-gpt6sol-production", "binary-cascades"} and method["status"] != "blocked":
+            raise DocumentationError("unverified production/binary invocation methods must remain blocked")
+        if method["model"] is not None:
+            _keys(method["model"], "model")
+        # Method parameters are the only extensible object: scalar defaults with
+        # stable bounded names, never arbitrary nested metadata or asset blobs.
+        allowed_parameters = {"s5_minilm_weight", "s5_lexical_weight", "selection_digest"} if method["name"] in {"S5a", "S5b", "S5c"} else set()
+        if not isinstance(method["parameters"], dict) or not set(method["parameters"]) <= allowed_parameters or any(not isinstance(value, str) for value in method["parameters"].values()):
+            raise DocumentationError("method parameters must be approved scalar configuration defaults")
+    for name, kind in (("datasets", "dataset"), ("controls", "control"), ("evidence", "evidence"), ("versions", "version")):
+        for item in payload[name]:
+            _keys(item, kind)
+            _url(item["source_url"])
+            if kind == "dataset" and item["suite_id"] not in ids["suites"] | {"rag.dataset.v3"}:
+                raise DocumentationError("dataset has missing suite reference")
+            if kind == "evidence":
+                for field in ("counts", "metrics", "runtime"):
+                    if not isinstance(item[field], dict) or not all(isinstance(k, str) and isinstance(v, str) for k, v in item[field].items()):
+                        raise DocumentationError("evidence metadata maps must contain approved string summaries")
+    for row in payload["reconciliation"]:
+        _keys(row, "reconciliation")
+        if not set(row["suite_ids"]) <= ids["suites"] or not set(row["missing_suite_ids"]) <= ids["suites"]:
+            raise DocumentationError("unknown suite in discovery reconciliation")
+    if "references" in payload:
+        validate_references(payload["references"], payload)
+
+
+def _read_json(path: Path) -> Any:
+    raw = path.read_bytes()
+    if len(raw) > MAX_BUNDLE_BYTES:
+        raise DocumentationError(f"oversized JSON: {path.name}")
+    def no_duplicates(pairs):
+        obj = {}
+        for key, value in pairs:
+            if key in obj:
+                raise DocumentationError(f"duplicate JSON key: {key}")
+            obj[key] = value
+        return obj
+    try:
+        return json.loads(raw.decode("utf-8-sig"), object_pairs_hook=no_duplicates, parse_constant=lambda v: (_ for _ in ()).throw(DocumentationError(f"invalid numeric constant: {v}")))
+    except (ValueError, UnicodeError) as error:
+        raise DocumentationError(f"invalid JSON in {path.name}: {error}") from error
+
+
+def _trees(root: Path) -> dict[str, ast.Module]:
+    return {module: ast.parse((root / f"src/sphynx/{module}.py").read_text(encoding="utf-8-sig"), filename=f"{module}.py") for module in API_MODULES}
+
+
+def _find(tree: ast.Module, name: str) -> ast.FunctionDef:
+    pieces = name.split(".")
+    nodes = tree.body
+    for piece in pieces:
+        matches = [node for node in nodes if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)) and node.name == piece]
+        if len(matches) != 1:
+            raise DocumentationError(f"missing or ambiguous public API: {name}")
+        found = matches[0]
+        nodes = found.body
+    if not isinstance(found, (ast.FunctionDef, ast.AsyncFunctionDef)):
+        raise DocumentationError(f"API is not a function: {name}")
+    return found
+
+
+def _interface(module: str, name: str, node: ast.FunctionDef, commit: str, descriptions: dict) -> dict:
+    args = copy.deepcopy(node.args)
+    if "." in name and args.args and args.args[0].arg in {"self", "cls"}:
+        args.args.pop(0)
+    required_count = len(args.posonlyargs) + len(args.args) - len(args.defaults)
+    positions = [(arg, "positional_only" if index < len(args.posonlyargs) else "positional_or_keyword", None if index < required_count else args.defaults[index-required_count], index < required_count) for index, arg in enumerate([*args.posonlyargs, *args.args])]
+    if args.vararg:
+        positions.append((args.vararg, "var_positional", None, False))
+    positions.extend((arg, "keyword_only", default, default is None) for arg, default in zip(args.kwonlyargs, args.kw_defaults))
+    if args.kwarg:
+        positions.append((args.kwarg, "var_keyword", None, False))
+    public_module = PUBLIC_API_NAMESPACES.get(module)
+    identity = f"{public_module}.{name}" if public_module else f"sphynx.{name}"
+    curated = descriptions.get(identity, {})
+    parameters = []
+    for arg, kind, default, required in positions:
+        explanation = curated.get("parameters", {}).get(arg.arg, {})
+        parameters.append({"name": arg.arg, "type": ast.unparse(arg.annotation) if arg.annotation else "Unannotated", "kind": kind, "required": required, "default": ast.unparse(default) if default is not None else None, "description": explanation.get("description", _parameter_help(arg.arg)), "accepted": explanation.get("accepted", [])})
+    returns = ast.unparse(node.returns) if node.returns else "Unannotated"
+    return {"id": identity, "module": public_module or f"sphynx.{module}", "signature": f"{name}({ast.unparse(args)})" + (f" -> {returns}" if node.returns else ""), "parameters": parameters, "returns": returns, "summary": curated.get("summary", (ast.get_docstring(node) or "See the measured boundary, input requirements, and known gaps for the related suite.").split("\n")[0]), "source_url": f"https://github.com/sable-inc/sphynx/blob/{commit}/src/sphynx/{module}.py#L{node.lineno}"}
+
+
+def _parameter_help(name: str) -> str:
+    explanations = {
+        "candidate_pr": "Allowed candidate GitHub PR URL. Hosted admission is checked independently.",
+        "expected_head_sha": "Complete current PR head guard; it does not select a historical commit.",
+        "expected_baseline_sha": "Complete main baseline head guard, currently restricted to registered-main-reflex-lexical:v1.",
+        "candidate_method": "Optional family selector. The admitted MiniLM root uses no selector; other research families are not hosted admitted.",
+        "suite": "Evaluation ID; hosted submission admits only rag.rerank.v1 and rag.rerank.public.v1.",
+        "baseline": "Separate candidate baseline session. supplied-score:v1 uses provided BM25 scores, without fresh retrieval.",
+        "parameters": "Protocol-specific allowlisted parameters; undocumented keys fail contract resolution.",
+        "expected_sha256": "Pinned approved input digest; metadata does not grant private data access.",
+        "dataset_path": "Owner-provided approved dataset file; raw data stays outside documentation artifacts.",
+        "output_dir": "Local output directory for saved captures/reports.",
+        "adapter": "Explicit local trusted adapter; local execution is not hosted isolation.",
+        "synthetic": "Use only explicit synthetic fixtures where supported.",
+        "judgments": "Independent capture-bound review. Missing review remains unavailable.",
+        "on_progress": "Optional callback for progress messages while waiting.",
+        "timeout": "Maximum wait/request duration; failures propagate as documented client errors.",
+        "token": "Read from existing protected configuration; never publish credentials or put them in example command arguments.",
+    }
+    return explanations.get(name, "Declared SDK argument. Follow the pinned source type/default and the suite's data and eligibility requirements.")
+
+
+def extract_api(root: Path, commit: str, descriptions: dict | None = None) -> list[dict]:
+    trees = _trees(root)
+    return sorted((_interface(module, name, _find(trees[module], name), commit, descriptions or {}) for module, names in API_MODULES.items() for name in names), key=lambda item: item["id"])
+
+
+def _definition_statuses(root: Path) -> dict[str, str]:
+    statuses = {}
+    for module in ("evals", "public_eval"):
+        tree = ast.parse((root / f"src/sphynx/{module}.py").read_text(encoding="utf-8-sig"))
+        literals = {node.targets[0].id: node.value.value for node in tree.body if isinstance(node, ast.Assign) and len(node.targets) == 1 and isinstance(node.targets[0], ast.Name) and isinstance(node.value, ast.Constant)}
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Call) and isinstance(node.func, ast.Name) and node.func.id == "EvaluationDefinition" and len(node.args) >= 4:
+                identity = node.args[0].value if isinstance(node.args[0], ast.Constant) else literals.get(node.args[0].id) if isinstance(node.args[0], ast.Name) else None
+                status = node.args[3].value if isinstance(node.args[3], ast.Constant) else None
+                if identity and status:
+                    statuses[identity] = status
+    return statuses
+
+
+def _metadata_expression(node: ast.AST, names: dict[str, Any]) -> Any:
+    """Interpret only literal schema constructors, never Python or SDK code."""
+    if isinstance(node, ast.Constant):
+        return node.value
+    if isinstance(node, (ast.List, ast.Tuple)):
+        return [_metadata_expression(item, names) for item in node.elts]
+    if isinstance(node, ast.Dict):
+        return {_metadata_expression(key, names): _metadata_expression(value, names) for key, value in zip(node.keys, node.values)}
+    if isinstance(node, ast.Name) and node.id in names:
+        return names[node.id]
+    if isinstance(node, ast.Subscript):
+        return _metadata_expression(node.value, names)[_metadata_expression(node.slice, names)]
+    if isinstance(node, ast.Call) and isinstance(node.func, ast.Name) and node.func.id in {"_object", "_integer", "_reporting", "_copy"}:
+        arguments = [_metadata_expression(arg, names) for arg in node.args]
+        keywords = {item.arg: _metadata_expression(item.value, names) for item in node.keywords}
+        if node.func.id == "_object":
+            schema = {"type": "object", "properties": arguments[0], "required": keywords.get("required", []), "additionalProperties": False}
+            if "default" in keywords:
+                schema["default"] = keywords["default"]
+            return schema
+        if node.func.id == "_integer":
+            return {"type": "integer", "default": arguments[0], "minimum": arguments[1], "maximum": arguments[2]}
+        if node.func.id == "_reporting":
+            return {"type": "object", "properties": {"format": {"type": "string", "enum": ["markdown", "json"], "default": "markdown"}}, "required": [], "additionalProperties": False, "default": {}}
+        if node.func.id == "_copy":
+            return copy.deepcopy(arguments[0])
+    raise DocumentationError(f"schema expression is outside the metadata allowlist: {type(node).__name__}")
+
+
+def extract_parameter_schemas(root: Path) -> dict[str, dict]:
+    schemas = {}
+    for module, function in (("evals", "default_evaluation_registry"), ("public_eval", "public_definition")):
+        tree = ast.parse((root / f"src/sphynx/{module}.py").read_text(encoding="utf-8-sig"))
+        names = {node.targets[0].id: node.value.value for node in tree.body if isinstance(node, ast.Assign) and len(node.targets) == 1 and isinstance(node.targets[0], ast.Name) and isinstance(node.value, ast.Constant)}
+        body = _find(tree, function).body
+        for node in body:
+            if not isinstance(node, ast.Assign) or len(node.targets) != 1:
+                continue
+            target = node.targets[0]
+            if isinstance(target, ast.Name) and target.id in {"bank", "legacy", "configurable", "props", "schema"}:
+                names[target.id] = _metadata_expression(node.value, names)
+            elif isinstance(target, ast.Subscript) and isinstance(target.value, ast.Name) and target.value.id == "props":
+                names["props"][_metadata_expression(target.slice, names)] = _metadata_expression(node.value, names)
+        if module == "evals":
+            schemas["rag.rerank.v1"] = names["legacy"]
+            schemas["rag.rerank.v2"] = names["configurable"]
+            for node in ast.walk(tree):
+                if isinstance(node, ast.Call) and isinstance(node.func, ast.Name) and node.func.id == "EvaluationDefinition" and isinstance(node.args[0], ast.Constant) and node.args[0].value == "audio.similarity.v1":
+                    schemas["audio.similarity.v1"] = _metadata_expression(node.args[6], names)
+        else:
+            schemas["rag.rerank.public.v1"] = names["schema"]
+    return schemas
+
+
+def flatten_parameter_schema(schema: dict) -> list[dict]:
+    rows = {}
+    def visit(node, prefix="", required=False, inherited=None):
+        default = node.get("default", inherited)
+        if "oneOf" in node:
+            for branch in node["oneOf"]:
+                visit(branch, prefix, required, default)
+        elif node.get("type") == "object":
+            for name, child in node["properties"].items():
+                child_default = default.get(name) if isinstance(default, dict) else None
+                visit(child, f"{prefix}.{name}" if prefix else name, name in node.get("required", []), child_default)
+        else:
+            row = {"name": prefix, "type": node.get("type", "union"), "required": required and default is None, "default": default, "accepted": [str(value).lower() if type(value) is bool else str(value) for value in node.get("enum", [])]}
+            if prefix in rows:
+                row["accepted"] = sorted(set(rows[prefix]["accepted"]) | set(row["accepted"]))
+                row["default"] = rows[prefix]["default"] if rows[prefix]["default"] is not None else row["default"]
+                row["required"] = rows[prefix]["required"] and row["required"]
+            rows[prefix] = row
+    visit(schema)
+    return list(rows.values())
+
+
+def snapshot_contract(root: Path, *, commit: str, tree: str, wheel_sha256: str) -> dict:
+    """Create a reviewable source lock from an explicitly reviewed pinned source."""
+    _hash(commit, "source commit", 40)
+    _hash(tree, "source tree", 40)
+    _hash(wheel_sha256, "wheel digest")
+    version = tomllib.loads((root / "pyproject.toml").read_text(encoding="utf-8-sig"))["project"]["version"]
+    interfaces = extract_api(root, commit)
+    # Python/TOML source is interpreted as UTF-8 text. Normalize a UTF-8 BOM
+    # and universal line endings only, so Git checkout EOL settings do not
+    # change receipts for semantically identical reviewed source text.
+    receipts = {path: sha256((root / path).read_text(encoding="utf-8-sig").replace("\r\n", "\n").replace("\r", "\n").encode("utf-8")) for path in SOURCE_FILES}
+    return {"schema_version": "sphynx.docs.source-contract.v1", "sdk_version": version, "source_commit": commit, "source_tree": tree, "wheel_sha256": wheel_sha256, "source_receipts": receipts, "source_receipts_format": SOURCE_RECEIPTS_FORMAT, "signatures": {item["id"]: item["signature"] for item in interfaces}, "definition_statuses": _definition_statuses(root), "parameter_schemas": extract_parameter_schemas(root)}
+
+
+def build_payload(root: Path, *, release_id: str | None = None) -> tuple[dict, dict, dict]:
+    public = root / "docs/public"
+    lock = _read_json(public / "source-contract.v1.json")
+    current = snapshot_contract(root, commit=lock["source_commit"], tree=lock["source_tree"], wheel_sha256=lock["wheel_sha256"])
+    if current != lock:
+        changed = [key for key in current if current[key] != lock.get(key)]
+        raise DocumentationError(f"stale documentation/source lock: changed {', '.join(changed)}; review and refresh source contract")
+    content = _read_json(public / "content.v1.json")
+    catalog = _read_json(public / "catalog.v1.json")
+    release = _read_json(public / "release.v1.json")
+    _keys(release, "release")
+    if release["exporter_version"] != EXPORTER_VERSION:
+        raise DocumentationError("curated release must select the current exporter version")
+    for field in ("sdk_version", "source_commit", "source_tree", "wheel_sha256"):
+        if release[field] != lock[field]:
+            raise DocumentationError(f"release/source contract identity mismatch: {field}")
+    if release_id is not None:
+        release["id"] = release_id
+    if set(content) != {"pages", "suites", "evidence", "versions", "known_gaps", "api_descriptions"} or set(catalog) != {"families", "methods", "datasets", "controls"}:
+        raise DocumentationError("unapproved curated source keys")
+    api = extract_api(root, lock["source_commit"], content["api_descriptions"])
+    interface_map = {item["id"]: item for item in api}
+    if set(content["api_descriptions"]) != set(interface_map):
+        raise DocumentationError("missing or stale public API documentation descriptions")
+    for identity, description in content["api_descriptions"].items():
+        if identity not in interface_map or set(description) - {"summary", "parameters"}:
+            raise DocumentationError(f"unknown or unapproved API description: {identity}")
+        names = {parameter["name"] for parameter in interface_map[identity]["parameters"]}
+        if set(description.get("parameters", {})) != names:
+            raise DocumentationError(f"stale parameter descriptions: {identity}")
+        for explanation in description.get("parameters", {}).values():
+            if not isinstance(explanation, dict) or set(explanation) != {"description", "accepted"}:
+                raise DocumentationError(f"invalid API parameter explanation: {identity}")
+    payload = {
+        "schema_version": SCHEMA,
+        "release": release,
+        **{key: value for key, value in content.items() if key != "api_descriptions"}, **catalog, "api": api,
+        "reconciliation": [
+            {"discovery": "list_packs", "suite_ids": ["rag.rerank.v1", "rag.rerank.sable.dev.v1", "rag.rerank.beir.v1", "rag.invoke.v1", "rag.retrieve.v1", "rag.question_robustness.v1"], "missing_suite_ids": ["rag.chunk.v1", "rag.pipeline.v1", "rag.full_rag.v1", "rag.rerank.public.v1"], "explanation": "Six local pack descriptors are not exhaustive SDK capability discovery. The hosted public definition and separately implemented DatasetV3 APIs are reconciled here."},
+            {"discovery": "list_evals", "suite_ids": ["rag.rerank.v1", "rag.rerank.public.v1", "rag.rerank.v2", "audio.similarity.v1"], "missing_suite_ids": sorted(IMPLEMENTED_IDS - HOSTED_IDS), "explanation": "Two runnable definitions and two contract-only definitions do not enumerate local evaluation APIs."},
+            {"discovery": "list_datasets", "suite_ids": [], "missing_suite_ids": [], "explanation": "34 dataset descriptors describe metadata and loader readiness, not 34 evaluations or private-data approval."},
+        ],
+    }
+    reference_source = public / "reference.v1.json"
+    if reference_source.exists():
+        payload["references"] = _read_json(reference_source)
+    statuses = lock["definition_statuses"]
+    for suite in payload["suites"]:
+        if suite["id"] in statuses and ("runnable" if suite["status"] == "implemented" else "contract_only") != statuses[suite["id"]]:
+            raise DocumentationError(f"stale suite status: {suite['id']}")
+        if suite["id"] in lock["parameter_schemas"]:
+            documented = {parameter["name"]: parameter for parameter in suite["parameters"]}
+            for parameter in flatten_parameter_schema(lock["parameter_schemas"][suite["id"]]):
+                actual = documented.get(parameter["name"])
+                if actual is None:
+                    raise DocumentationError(f"missing suite parameter documentation: {suite['id']}.{parameter['name']}")
+                if actual["default"] != parameter["default"] or actual["required"] != parameter["required"] or not set(parameter["accepted"]) <= set(actual["accepted"]):
+                    raise DocumentationError(f"stale suite parameter default/required/options: {suite['id']}.{parameter['name']}")
+    validate_payload(payload)
+    return payload, catalog, lock
+
+
+def export_bundle(source_root: str | Path, output_dir: str | Path, *, release_id: str | None = None, build_time_utc: str | None = None) -> dict:
+    """Write deterministic public JSON and an independently timestamped manifest."""
+    root, output = Path(source_root), Path(output_dir)
+    payload, catalog, lock = build_payload(root, release_id=release_id)
+    raw = canonical_bytes(payload)
+    catalog_raw = canonical_bytes(catalog)
+    manifest = {"schema_version": MANIFEST_SCHEMA, "content_sha256": sha256(raw), "content_bytes": len(raw), "catalog_sha256": sha256(catalog_raw), "source_receipts": lock["source_receipts"], "source_receipts_format": SOURCE_RECEIPTS_FORMAT, "source_receipts_sha256": sha256(canonical_bytes(lock["source_receipts"])), "build_time_utc": build_time_utc or datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"), "exporter_sha256": sha256(Path(__file__).read_bytes())}
+    if "references" in payload:
+        manifest["references_sha256"] = sha256(canonical_bytes(payload["references"]))
+        curated_files = ["catalog.v1.json", "content.v1.json", "release.v1.json", "reference.v1.json"]
+        documentation_receipts = {f"docs/public/{name}": sha256(canonical_bytes(_read_json(root / "docs/public" / name))) for name in curated_files}
+        manifest["documentation_source_receipts"] = documentation_receipts
+        manifest["documentation_source_receipts_sha256"] = sha256(canonical_bytes(documentation_receipts))
+    files = (("payload.json", raw), ("catalog.json", catalog_raw), ("manifest.json", canonical_bytes(manifest)))
+    for name, data in files:
+        destination = output / name
+        if destination.exists() and name != "manifest.json" and destination.read_bytes() != data:
+            raise DocumentationError("immutable release path contains different content; use a new release ID/output directory")
+    output.mkdir(parents=True, exist_ok=True)
+    for name, data in files:
+        destination = output / name
+        destination.write_bytes(data)
+    return manifest
+
+
+def verify_bundle(bundle_dir: str | Path, *, expected_sha256: str) -> dict:
+    """Reject malformed/unapproved artifacts before an Evals Lab import."""
+    _hash(expected_sha256, "approved content digest")
+    root = Path(bundle_dir)
+    raw = (root / "payload.json").read_bytes()
+    if len(raw) > MAX_BUNDLE_BYTES:
+        raise DocumentationError("documentation payload exceeds size limit")
+    manifest = _read_json(root / "manifest.json")
+    _keys(manifest, "manifest", optional=("references_sha256", "documentation_source_receipts", "documentation_source_receipts_sha256"))
+    if manifest["source_receipts_format"] != SOURCE_RECEIPTS_FORMAT:
+        raise DocumentationError("unsupported source receipt normalization")
+    if type(manifest["content_bytes"]) is not int or manifest["schema_version"] != MANIFEST_SCHEMA or manifest["content_sha256"] != expected_sha256 or sha256(raw) != expected_sha256 or manifest["content_bytes"] != len(raw):
+        raise DocumentationError("documentation content digest/size mismatch")
+    for key in ("catalog_sha256", "source_receipts_sha256", "exporter_sha256"):
+        _hash(manifest[key], key)
+    receipts = manifest["source_receipts"]
+    if set(receipts) not in (set(SOURCE_FILES), set(PREVIOUS_SOURCE_FILES), set(LEGACY_SOURCE_FILES)) or any(not re.fullmatch(r"(?:pyproject\.toml|src/sphynx/(?:rag_papers/)?[a-z_]+\.py)", path) for path in receipts):
+        raise DocumentationError("unapproved source receipt paths")
+    for value in receipts.values():
+        _hash(value, "source receipt")
+    if sha256(canonical_bytes(receipts)) != manifest["source_receipts_sha256"]:
+        raise DocumentationError("source receipt digest mismatch")
+    payload = _read_json(root / "payload.json")
+    catalog = _read_json(root / "catalog.json")
+    if sha256((root / "catalog.json").read_bytes()) != manifest["catalog_sha256"] or catalog != {key: payload[key] for key in ("families", "methods", "datasets", "controls")}:
+        raise DocumentationError("catalogue digest/projection mismatch")
+    validate_payload(payload)
+    reference_receipt_fields = {"references_sha256", "documentation_source_receipts", "documentation_source_receipts_sha256"}
+    if set(manifest) & reference_receipt_fields and not reference_receipt_fields <= set(manifest):
+        raise DocumentationError("reference source receipts must be supplied together")
+    if "references" in payload:
+        if "references_sha256" not in manifest or sha256(canonical_bytes(payload["references"])) != manifest["references_sha256"]:
+            raise DocumentationError("reference digest mismatch")
+    elif "references_sha256" in manifest:
+        raise DocumentationError("reference digest present without reference content")
+    has_documentation_receipts = "documentation_source_receipts" in manifest
+    if has_documentation_receipts != ("documentation_source_receipts_sha256" in manifest):
+        raise DocumentationError("documentation source receipts require their digest")
+    if has_documentation_receipts:
+        documentation_receipts = manifest["documentation_source_receipts"]
+        expected_paths = {"docs/public/catalog.v1.json", "docs/public/content.v1.json", "docs/public/release.v1.json"}
+        if "references" in payload:
+            expected_paths.add("docs/public/reference.v1.json")
+        if not isinstance(documentation_receipts, dict) or set(documentation_receipts) != expected_paths:
+            raise DocumentationError("unapproved documentation receipt paths")
+        for value in documentation_receipts.values():
+            _hash(value, "documentation source receipt")
+        if sha256(canonical_bytes(documentation_receipts)) != manifest["documentation_source_receipts_sha256"]:
+            raise DocumentationError("documentation source receipt digest mismatch")
+        if "references" in payload and documentation_receipts["docs/public/reference.v1.json"] != manifest["references_sha256"]:
+            raise DocumentationError("reference source receipt mismatch")
+    return {"manifest": manifest, "payload": payload}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Sphynx metadata-only documentation exporter (implemented v1)")
+    sub = parser.add_subparsers(dest="command", required=True)
+    default_root = Path(__file__).resolve().parents[2]
+    for name in ("snapshot-contract", "check", "export"):
+        command = sub.add_parser(name)
+        command.add_argument("--source-root", type=Path, default=default_root)
+        if name == "snapshot-contract":
+            command.add_argument("--source-commit", required=True)
+            command.add_argument("--source-tree", required=True)
+            command.add_argument("--wheel-sha256", required=True)
+        if name == "export":
+            command.add_argument("--output", type=Path, required=True)
+            command.add_argument("--release-id")
+            command.add_argument("--build-time-utc")
+    verify = sub.add_parser("verify")
+    verify.add_argument("--bundle-dir", type=Path, required=True)
+    verify.add_argument("--expected-sha256", required=True)
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "snapshot-contract":
+            contract = snapshot_contract(args.source_root, commit=args.source_commit, tree=args.source_tree, wheel_sha256=args.wheel_sha256)
+            path = args.source_root / "docs/public/source-contract.v1.json"
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_bytes(canonical_bytes(contract))
+            print(f"Review source contract: {path}")
+        elif args.command == "check":
+            payload, _, _ = build_payload(args.source_root)
+            print(f"Documentation check passed: {len(payload['suites'])} suites, {len(payload['methods'])} methods, {len(payload['api'])} API entries; no evaluation executed")
+        elif args.command == "export":
+            manifest = export_bundle(args.source_root, args.output, release_id=args.release_id, build_time_utc=args.build_time_utc)
+            print(json.dumps({"output": str(args.output), "content_sha256": manifest["content_sha256"], "content_bytes": manifest["content_bytes"]}))
+        else:
+            result = verify_bundle(args.bundle_dir, expected_sha256=args.expected_sha256)
+            print(f"Verified approved documentation release: {result['payload']['release']['id']}")
+        return 0
+    except (DocumentationError, OSError, KeyError, TypeError, SyntaxError) as error:
+        print(f"Documentation error: {error}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())