qwen-sci 0.2.2__py3-none-any.whl

src/agents/research_plan_author/latex_safety.py

@@ -0,0 +1,159 @@
+"""Small, shared safety primitives for generated LaTeX and BibTeX."""
+
+from __future__ import annotations
+
+import re
+
+
+class LatexSafetyError(ValueError):
+    """Raised when document-controlled text is unsafe for the renderer."""
+
+
+_OBSERVED_RESULT_LANGUAGE = re.compile(
+    r"\b(?:we|this\s+(?:study|research|work|investigation|analysis)|"
+    r"the\s+(?:study|experiment|analysis|evaluation))\s+(?:have\s+)?"
+    r"(?:observed|found|demonstrated|showed|measured|established|confirmed|revealed)\b"
+    r"|\b(?:the\s+)?(?:results|experiments|analyses|data|evaluation)\s+(?:have\s+)?"
+    r"(?:observed|found|demonstrated|showed|measured|established|confirmed|revealed)\b",
+    re.IGNORECASE,
+)
+_FORBIDDEN_TEX_COMMANDS = re.compile(
+    r"\\(?:input|include|write|openout|read|catcode|newcommand|renewcommand|def|gdef|"
+    r"usepackage|documentclass|immediate|write18|csname|expandafter|every|loop|directlua)\b",
+    re.IGNORECASE,
+)
+_MATH_COMMAND = re.compile(r"\\([A-Za-z]+)")
+_ALLOWED_MATH_COMMANDS = {
+    "alpha", "beta", "gamma", "delta", "epsilon", "varepsilon", "zeta", "eta", "theta",
+    "vartheta", "iota", "kappa", "lambda", "mu", "nu", "xi", "pi", "rho", "sigma",
+    "tau", "upsilon", "phi", "varphi", "chi", "psi", "omega", "Gamma", "Delta", "Theta",
+    "Lambda", "Xi", "Pi", "Sigma", "Phi", "Psi", "Omega", "frac", "sqrt", "sum", "prod",
+    "int", "lim", "log", "ln", "exp", "sin", "cos", "tan", "min", "max", "sup", "inf",
+    "forall", "exists", "in", "notin", "subset", "subseteq", "supset", "supseteq", "cup", "cap",
+    "to", "rightarrow", "Rightarrow", "Leftarrow", "Leftrightarrow", "leq", "geq", "neq", "approx",
+    "equiv", "times", "cdot", "pm", "mp", "partial", "nabla", "infty", "ldots", "dots", "mathrm",
+    "mathcal", "mathbb", "mathbf", "operatorname", "left", "right", "langle", "rangle", "vert", "mid",
+}
+_ALLOWED_MATH_CHARS = re.compile(r"^[A-Za-z0-9\s+\-*/=<>(),.;:{}\[\]_\\^|!?'`]+$")
+_MATH_STRUCTURE = re.compile(
+    r"(?:[=<>]|[_^]|\\(?:frac|sqrt|sum|prod|int|lim|forall|exists|leq|geq|neq|approx|equiv|to|rightarrow|Rightarrow|Leftarrow|Leftrightarrow)\b)"
+)
+_MATH_IDENTIFIER_COMMAND = re.compile(
+    r"\\(?:operatorname|mathrm|mathcal|mathbb|mathbf)\s*\{[A-Za-z]+\}"
+)
+_LOWERCASE_PROSE_WORD = re.compile(r"\b[a-z]{3,}\b")
+_EQUATION_FRAGMENT_BOUNDARY = re.compile(r"\n[ \t]*\n+")
+
+
+def contains_observed_result_language(value: object) -> bool:
+    """Detect proposal-incompatible statements that present work as completed."""
+
+    return bool(_OBSERVED_RESULT_LANGUAGE.search(str(value or "")))
+
+
+def normalize_visible_text(value: object, *, label: str) -> str:
+    """Normalize visible text while rejecting unsupported control characters.
+
+    Author content may use any Unicode script. Text safety is enforced by
+    escaping and raw-TeX restrictions rather than by a language gate.
+    """
+
+    text = str(value or "")
+    if any(ord(character) < 32 and character not in "\n\r\t" for character in text):
+        raise LatexSafetyError(f"{label} contains an unsupported control character")
+    return text.replace("\r\n", "\n").replace("\r", "\n")
+
+
+def escape_latex_text(
+    value: object,
+    *,
+    label: str = "text",
+) -> str:
+    """Escape plain visible text; this intentionally never preserves raw TeX."""
+
+    text = normalize_visible_text(value, label=label)
+    replacements = {
+        "&": r"\&",
+        "%": r"\%",
+        "$": r"\$",
+        "#": r"\#",
+        "_": r"\_",
+        "{": r"\{",
+        "}": r"\}",
+        "~": r"\textasciitilde{}",
+        "^": r"\textasciicircum{}",
+        "\\": r"\textbackslash{}",
+    }
+    return "".join(replacements.get(character, character) for character in text)
+
+
+def safe_math_expression(value: object, *, label: str = "equation") -> str:
+    """Allow a deliberately small math-only subset and reject executable TeX."""
+
+    text = normalize_visible_text(value, label=label).strip()
+    if not text:
+        raise LatexSafetyError(f"{label} is empty")
+    if "$" in text or "\\begin" in text.casefold() or "\\end" in text.casefold():
+        raise LatexSafetyError(f"{label} must be a math expression, not a TeX environment")
+    if _FORBIDDEN_TEX_COMMANDS.search(text):
+        raise LatexSafetyError(f"{label} contains a forbidden TeX command")
+    if not _ALLOWED_MATH_CHARS.fullmatch(text):
+        raise LatexSafetyError(f"{label} contains unsupported math characters")
+    commands = _MATH_COMMAND.findall(text.replace(r"\\", " "))
+    unsupported = sorted({command for command in commands if command not in _ALLOWED_MATH_COMMANDS})
+    if unsupported:
+        raise LatexSafetyError(f"{label} contains unsupported math commands: {', '.join(unsupported)}")
+    if not _MATH_STRUCTURE.search(text):
+        raise LatexSafetyError(f"{label} must contain a mathematical relation or structure")
+    residual_text = _MATH_COMMAND.sub("", _MATH_IDENTIFIER_COMMAND.sub("", text))
+    if _LOWERCASE_PROSE_WORD.search(residual_text):
+        raise LatexSafetyError(f"{label} contains explanatory prose and must be split from its mathematics")
+    return text
+
+
+def split_equation_content(value: object, *, label: str = "equation") -> list[tuple[str, str]]:
+    """Partition an equation block into safe math expressions and visible prose.
+
+    A model may put sentence-level explanation around otherwise valid formulae.
+    Keeping these fragments distinct lets the renderer preserve the explanation
+    without sending it into a display-math environment.
+    """
+
+    text = normalize_visible_text(value, label=label).strip()
+    if not text:
+        raise LatexSafetyError(f"{label} is empty")
+    if "$" in text or "\\begin" in text.casefold() or "\\end" in text.casefold():
+        raise LatexSafetyError(f"{label} must be a math expression, not a TeX environment")
+    if _FORBIDDEN_TEX_COMMANDS.search(text):
+        raise LatexSafetyError(f"{label} contains a forbidden TeX command")
+    fragments = [
+        fragment.strip()
+        for fragment in _EQUATION_FRAGMENT_BOUNDARY.split(text)
+        if fragment.strip()
+    ]
+    result: list[tuple[str, str]] = []
+    for index, fragment in enumerate(fragments, start=1):
+        fragment_label = label if len(fragments) == 1 else f"{label} fragment {index}"
+        try:
+            result.append(("equation", safe_math_expression(fragment, label=fragment_label)))
+        except LatexSafetyError:
+            result.append(("prose", fragment))
+    return result
+
+
+def validate_citation_key(value: object) -> str:
+    key = str(value or "").strip()
+    if not re.fullmatch(r"[A-Za-z0-9._:+-]+", key):
+        raise LatexSafetyError(f"citation key is unsafe for BibTeX: {key!r}")
+    return key
+
+
+__all__ = [
+    "LatexSafetyError",
+    "contains_observed_result_language",
+    "escape_latex_text",
+    "normalize_visible_text",
+    "safe_math_expression",
+    "split_equation_content",
+    "validate_citation_key",
+]

src/agents/research_plan_author/llm_json.py

@@ -0,0 +1,74 @@
+"""Required JSON-only LLM invocation for Research Plan Author stages."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from threading import local
+from typing import Any, Optional
+
+from src.agents.experiment_design_agent.llm_json import (
+    JSON_OBJECT_RESPONSE_FORMAT,
+    RequiredJsonLLMError,
+    call_required_json,
+)
+from src.llm.provider_registry import resolve_model
+
+
+def build_author_json_llm_call(
+    *,
+    config: Any = None,
+    model: Optional[str] = None,
+    temperature: float | None = None,
+) -> Callable[..., object]:
+    """Build the configured Author callback while preserving strict JSON mode."""
+
+    holder = local()
+
+    def setting(value: Any, key: str, default: Any = "") -> Any:
+        if isinstance(value, Mapping):
+            return value.get(key, default)
+        return getattr(value, key, default)
+
+    def _call(prompt: str, **kwargs: Any) -> object:
+        if kwargs.get("response_format", JSON_OBJECT_RESPONSE_FORMAT) != JSON_OBJECT_RESPONSE_FORMAT:
+            raise RequiredJsonLLMError("research_plan_author: only JSON object response format is permitted")
+        runtime_config = config
+        if runtime_config is None:
+            from src.config import get_config
+
+            runtime_config = get_config()
+        author_config = setting(runtime_config, "research_plan_author", {})
+        authoring_config = setting(author_config, "authoring", {})
+        resolved_model = str(model or setting(author_config, "model") or "").strip()
+        provider_name = str(setting(author_config, "provider") or "").strip()
+        resolved_temperature = float(
+            setting(authoring_config, "temperature", 0.5) if temperature is None else temperature
+        )
+        if model:
+            provider_name = resolve_model(runtime_config, resolved_model).provider
+        agent = getattr(holder, "agent", None)
+        if agent is None:
+            from src.agents.idea_agent.agent.base import AgentBase
+
+            agent = AgentBase(config=runtime_config, provider_name=provider_name or None)
+            holder.agent = agent
+        if not resolved_model:
+            resolved_model = str(agent.provider.default_models.get("author") or "").strip()
+        if not resolved_model:
+            raise RequiredJsonLLMError("research_plan_author: no model is configured for the author LLM role")
+        return agent.chat(
+            prompt,
+            model=resolved_model,
+            response_format=JSON_OBJECT_RESPONSE_FORMAT,
+            temperature=resolved_temperature,
+        )
+
+    return _call
+
+
+__all__ = [
+    "JSON_OBJECT_RESPONSE_FORMAT",
+    "RequiredJsonLLMError",
+    "build_author_json_llm_call",
+    "call_required_json",
+]

src/agents/research_plan_author/markdown_renderer.py

@@ -0,0 +1,275 @@
+"""Deterministic Markdown views of structured Research Plan documents."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+import re
+from typing import Any
+
+from .theory_presentation import theory_block_presentation, theory_unit_registry, visible_theory_text
+
+
+_PRIVATE_PROVENANCE = re.compile(
+    r"\[?(?:survey:survey_markdown(?:#section-[A-Za-z0-9._:+-]+)?|anchor:[A-Za-z0-9_:+-]+(?:\.[A-Za-z0-9_:+-]+)*)\]?",
+    flags=re.IGNORECASE,
+)
+
+
+def _mapping(value: object) -> dict[str, Any]:
+    return dict(value) if isinstance(value, Mapping) else {}
+
+
+def _text(value: object) -> str:
+    return str(value or "").strip()
+
+
+def _visible(value: object) -> str:
+    return _PRIVATE_PROVENANCE.sub("", _text(value)).strip()
+
+
+def _visible_for_document(document: Mapping[str, Any], value: object) -> str:
+    return _visible(visible_theory_text(document, value))
+
+
+def _label_component(value: object) -> str:
+    component = re.sub(r"[^A-Za-z0-9:-]+", "-", _text(value)).strip("-:")
+    return component or "unnamed"
+
+
+def _equation_label(section_id: object, block_id: object) -> str:
+    return f"eq:{_label_component(section_id)}-{_label_component(block_id)}"
+
+
+def _document_equation_labels(document: Mapping[str, Any]) -> dict[str, str]:
+    labels: dict[str, str] = {}
+    for section in [*(document.get("sections") or []), *(document.get("appendices") or [])]:
+        if not isinstance(section, Mapping):
+            continue
+        section_id = _text(section.get("section_id"))
+        for block in section.get("blocks") or []:
+            if isinstance(block, Mapping) and _text(block.get("kind")) == "equation":
+                block_id = _text(block.get("block_id"))
+                if section_id and block_id:
+                    labels[f"{section_id}:{block_id}"] = _equation_label(section_id, block_id)
+    return labels
+
+
+def _equation_cross_references(block: Mapping[str, Any], *, equation_labels: Mapping[str, str]) -> str:
+    labels = [
+        equation_labels[reference_id]
+        for raw_reference_id in block.get("reference_block_ids") or []
+        if (reference_id := _text(raw_reference_id)) in equation_labels
+    ]
+    return "" if not labels else " See Eq. (" + ", ".join(labels) + ")."
+
+
+def _claim_map(document: Mapping[str, Any]) -> dict[str, Mapping[str, Any]]:
+    return {
+        _text(claim.get("claim_id")): claim
+        for claim in document.get("claim_provenance") or []
+        if isinstance(claim, Mapping) and _text(claim.get("claim_id"))
+    }
+
+
+def _citation_suffix(block: Mapping[str, Any], claims: Mapping[str, Mapping[str, Any]]) -> str:
+    keys: list[str] = []
+    for claim_id in block.get("claim_ids") or []:
+        claim = claims.get(_text(claim_id))
+        if not isinstance(claim, Mapping):
+            continue
+        for citation_key in claim.get("citation_keys") or []:
+            normalized = _text(citation_key)
+            if normalized and normalized not in keys:
+                keys.append(normalized)
+    return " " + " ".join(f"[@{key}]" for key in keys) if keys else ""
+
+
+def _block_markdown(
+    block: Mapping[str, Any],
+    *,
+    claims: Mapping[str, Mapping[str, Any]],
+    evaluation_markers: bool,
+    section_id: str,
+    document: Mapping[str, Any],
+    theory_registry: Mapping[str, Mapping[str, Any]],
+    equation_labels: Mapping[str, str],
+) -> str:
+    block_id = _text(block.get("block_id"))
+    marker = f"<!-- author:section={section_id} block={block_id} -->\n" if evaluation_markers else ""
+    heading = _visible_for_document(document, block.get("heading"))
+    kind = _text(block.get("kind"))
+    text = _visible_for_document(document, block.get("text"))
+    if not text:
+        return ""
+    prefix = f"### {heading}\n\n" if heading else ""
+    suffix = _citation_suffix(block, claims)
+    theory_prefix, _status = theory_block_presentation(
+        block,
+        claims=claims,
+        registry=theory_registry,
+    )
+    cross_references = _equation_cross_references(block, equation_labels=equation_labels)
+    if kind == "equation":
+        equation_label = equation_labels.get(_text(block.get("block_id")), "")
+        equation_prefix = f"**Equation [{equation_label}].**\n\n" if equation_label else ""
+        return marker + prefix + equation_prefix + "$$\n" + text + "\n$$" + suffix
+    if kind == "table" and theory_prefix:
+        return marker + prefix + f"**{theory_prefix}**\n\n" + text + cross_references + suffix
+    if theory_prefix:
+        return marker + prefix + f"**{theory_prefix}** " + text + cross_references + suffix
+    if kind == "definition":
+        return marker + prefix + "**Definition.** " + text + cross_references + suffix
+    if kind == "proposition":
+        return marker + prefix + "**Proposition (Candidate).** " + text + cross_references + suffix
+    if kind == "protocol":
+        return marker + prefix + "**Planned protocol.** " + text + cross_references + suffix
+    if kind == "outcome_branch":
+        return marker + prefix + "**Pre-registered Branch (Expected---Not Observed).** " + text + cross_references + suffix
+    if kind == "review_checklist":
+        return marker + prefix + "**Human-review checklist (Review-required).** " + text + cross_references + suffix
+    return marker + prefix + text + cross_references + suffix
+
+
+def _section_markdown(
+    section: Mapping[str, Any],
+    *,
+    claims: Mapping[str, Mapping[str, Any]],
+    evaluation_markers: bool,
+    document: Mapping[str, Any],
+    theory_registry: Mapping[str, Mapping[str, Any]],
+    document_equation_labels: Mapping[str, str],
+) -> str:
+    section_id = _text(section.get("section_id"))
+    title = _visible_for_document(document, section.get("title"))
+    equation_labels = {
+        **document_equation_labels,
+        **{
+            _text(block.get("block_id")): _equation_label(section_id, block.get("block_id"))
+            for block in section.get("blocks") or []
+            if isinstance(block, Mapping) and _text(block.get("kind")) == "equation"
+        },
+    }
+    lines = [f"## {title}"]
+    for block in section.get("blocks") or []:
+        if isinstance(block, Mapping):
+            rendered = _block_markdown(
+                block,
+                claims=claims,
+                evaluation_markers=evaluation_markers,
+                section_id=section_id,
+                document=document,
+                theory_registry=theory_registry,
+                equation_labels=equation_labels,
+            )
+            if rendered:
+                lines.append(rendered)
+    return "\n\n".join(lines)
+
+
+def _bibliography_markdown(document: Mapping[str, Any], claims: Mapping[str, Mapping[str, Any]]) -> str:
+    cited_keys = {
+        _text(key)
+        for claim in claims.values()
+        for key in claim.get("citation_keys") or []
+        if _text(key)
+    }
+    records = [
+        dict(record)
+        for record in document.get("citation_registry") or []
+        if isinstance(record, Mapping) and _text(record.get("citation_key")) in cited_keys
+    ]
+    lines = ["## References"]
+    if not records:
+        lines.append("No registered sources are cited in the visible manuscript.")
+        return "\n\n".join(lines)
+    for record in sorted(records, key=lambda item: _text(item.get("citation_key"))):
+        metadata = _mapping(record.get("bibliographic_metadata"))
+        authors = [_text(author) for author in metadata.get("authors") or [] if _text(author)]
+        author_text = authors[0] + (" et al." if len(authors) > 1 else "") if authors else "Registered source"
+        title = _visible(metadata.get("title")) or "Untitled work"
+        venue = _visible(metadata.get("venue"))
+        year = _visible(metadata.get("year"))
+        tail = ", ".join(item for item in (venue, year) if item)
+        entry = f"- [@{_text(record.get('citation_key'))}] {author_text}. *{title}*."
+        lines.append(entry + (f" {tail}." if tail else ""))
+    return "\n".join(lines)
+
+
+def render_research_plan_markdown(
+    document: Mapping[str, Any],
+    *,
+    evaluation_markers: bool = False,
+    compact_references: bool = False,
+) -> str:
+    """Render a complete, source-safe Markdown manuscript from one document."""
+
+    claims = _claim_map(document)
+    theory_registry = theory_unit_registry(document)
+    document_equation_labels = _document_equation_labels(document)
+    metadata = _mapping(document.get("document_metadata"))
+    title = _visible_for_document(document, metadata.get("title")) or "Research Plan"
+    lines = [f"# {title}"]
+    keywords = [
+        _visible_for_document(document, keyword)
+        for keyword in document.get("keywords") or []
+        if _visible_for_document(document, keyword)
+    ]
+    if keywords:
+        lines.append("**Keywords:** " + ", ".join(keywords))
+    abstract = _mapping(document.get("abstract"))
+    abstract_text = _visible_for_document(document, abstract.get("text"))
+    if abstract_text:
+        lines.append("## Abstract\n\n" + abstract_text)
+    for section in document.get("sections") or []:
+        if not isinstance(section, Mapping) or _text(section.get("section_id")) == "references":
+            continue
+        lines.append(
+            _section_markdown(
+                section,
+                claims=claims,
+                evaluation_markers=evaluation_markers,
+                document=document,
+                theory_registry=theory_registry,
+                document_equation_labels=document_equation_labels,
+            )
+        )
+    appendices = [section for section in document.get("appendices") or [] if isinstance(section, Mapping)]
+    if appendices:
+        lines.append("# Appendices")
+        lines.extend(
+            _section_markdown(
+                section,
+                claims=claims,
+                evaluation_markers=evaluation_markers,
+                document=document,
+                theory_registry=theory_registry,
+                document_equation_labels=document_equation_labels,
+            )
+            for section in appendices
+        )
+    if compact_references:
+        cited_count = len(
+            {
+                _text(key)
+                for claim in claims.values()
+                for key in claim.get("citation_keys") or []
+                if _text(key)
+            }
+        )
+        lines.append(f"## References\n\nThe manuscript uses {cited_count} registered citation key(s).")
+    else:
+        lines.append(_bibliography_markdown(document, claims))
+    return "\n\n".join(part for part in lines if part.strip()).strip() + "\n"
+
+
+def render_quality_review_markdown(document: Mapping[str, Any]) -> str:
+    """Render the full prose with private stable markers for quality review only."""
+
+    return render_research_plan_markdown(
+        document,
+        evaluation_markers=True,
+        compact_references=True,
+    )
+
+
+__all__ = ["render_quality_review_markdown", "render_research_plan_markdown"]

src/agents/research_plan_author/pdf_validator.py

@@ -0,0 +1,149 @@
+"""Structural and first-page render validation for generated Author PDFs."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+import subprocess
+import tempfile
+from time import perf_counter
+from typing import Any
+
+
+PDF_VALIDATION_SCHEMA_VERSION = "research_plan_author_pdf_validation_v1"
+
+
+class PdfValidationError(RuntimeError):
+    """Raised when a generated PDF cannot be parsed or rendered safely."""
+
+    def __init__(self, message: str, *, report: dict[str, Any] | None = None) -> None:
+        super().__init__(message)
+        self.report = dict(report) if isinstance(report, dict) else None
+
+
+@dataclass(frozen=True)
+class PdfValidationResult:
+    valid: bool
+    report: dict[str, Any]
+
+
+def validate_pdf(
+    pdf_path: str | Path,
+    *,
+    renderer: str | Path,
+    timeout_seconds: int = 60,
+    logger: Any | None = None,
+) -> PdfValidationResult:
+    """Require a parseable PDF with at least one renderable first page."""
+
+    source = Path(pdf_path).expanduser().resolve()
+    renderer_path = Path(renderer).expanduser().resolve()
+    if not source.is_file() or source.stat().st_size == 0:
+        raise PdfValidationError(f"generated PDF does not exist or is empty: {source}")
+    if not renderer_path.is_file():
+        raise PdfValidationError(f"PDF renderer is not an executable file: {renderer_path}")
+    parser_report: dict[str, Any] = {}
+    try:
+        from pypdf import PdfReader
+
+        reader = PdfReader(str(source))
+        page_count = len(reader.pages)
+        if page_count < 1:
+            raise PdfValidationError("generated PDF has no pages")
+        first_page = reader.pages[0]
+        box = first_page.mediabox
+        width = float(box.width)
+        height = float(box.height)
+        if width <= 0 or height <= 0:
+            raise PdfValidationError("generated PDF has invalid first-page dimensions")
+        extracted = ""
+        for page in reader.pages[: min(page_count, 3)]:
+            try:
+                extracted += page.extract_text() or ""
+            except Exception:
+                continue
+        parser_report = {
+            "backend": "pypdf",
+            "status": "parsed",
+            "page_count": page_count,
+            "first_page_width": width,
+            "first_page_height": height,
+            "extractable_text": bool(extracted.strip()),
+            "warning": "non_text_pdf" if not extracted.strip() else "",
+        }
+    except PdfValidationError:
+        raise
+    except Exception as error:
+        raise PdfValidationError(
+            f"pypdf could not parse generated PDF: {type(error).__name__}: {error}",
+            report={
+                "schema_version": PDF_VALIDATION_SCHEMA_VERSION,
+                "generated_at": datetime.now(timezone.utc).isoformat(timespec="milliseconds"),
+                "valid": False,
+                "pdf_path": str(source),
+                "file_size_bytes": source.stat().st_size,
+                "parser": {"backend": "pypdf", "status": "parse_failed", "error": type(error).__name__},
+                "renderer": {"backend": "pdftoppm", "status": "not_started"},
+            },
+        ) from error
+    with tempfile.TemporaryDirectory(prefix="research-plan-author-pdf-") as temporary_root:
+        prefix = Path(temporary_root) / "page"
+        command = [str(renderer_path), "-f", "1", "-l", "1", "-png", str(source), str(prefix)]
+        started_at = perf_counter()
+        if logger is not None:
+            logger.emit("pdf_validation", "render_started", status="RUNNING", renderer=str(renderer_path))
+        try:
+            completed = subprocess.run(
+                command,
+                shell=False,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                timeout=max(1, int(timeout_seconds)),
+                check=False,
+            )
+        except subprocess.TimeoutExpired as error:
+            raise PdfValidationError(f"PDF first-page renderer timed out after {timeout_seconds} seconds") from error
+        except OSError as error:
+            raise PdfValidationError(f"PDF first-page renderer could not start: {error}") from error
+        images = sorted(Path(temporary_root).glob("page-*.png"))
+        render_success = completed.returncode == 0 and bool(images) and images[0].stat().st_size > 0
+        render_report = {
+            "backend": "pdftoppm",
+            "status": "rendered" if render_success else "render_failed",
+            "command": [str(value) for value in command],
+            "return_code": completed.returncode,
+            "elapsed_ms": round((perf_counter() - started_at) * 1000, 3),
+            "rendered_first_page_bytes": images[0].stat().st_size if images else 0,
+            "stderr_tail": (completed.stderr or "")[-2000:],
+        }
+        if logger is not None:
+            logger.emit(
+                "pdf_validation",
+                "render_completed" if render_success else "render_failed",
+                level="INFO" if render_success else "ERROR",
+                status="COMPLETED" if render_success else "FAILED",
+                return_code=completed.returncode,
+                elapsed_ms=render_report["elapsed_ms"],
+            )
+        report = {
+            "schema_version": PDF_VALIDATION_SCHEMA_VERSION,
+            "generated_at": datetime.now(timezone.utc).isoformat(timespec="milliseconds"),
+            "valid": render_success,
+            "pdf_path": str(source),
+            "file_size_bytes": source.stat().st_size,
+            "parser": parser_report,
+            "renderer": render_report,
+        }
+        if not render_success:
+            raise PdfValidationError(
+                "PDF first-page render validation failed: "
+                + (completed.stderr or completed.stdout or "renderer produced no PNG")[-1000:],
+                report=report,
+            )
+    return PdfValidationResult(valid=True, report=report)
+
+
+__all__ = ["PDF_VALIDATION_SCHEMA_VERSION", "PdfValidationError", "PdfValidationResult", "validate_pdf"]