reader-workbench 1.0.0__py3-none-any.whl

reader_workbench/maintenance/docs.py

@@ -0,0 +1,335 @@
+from __future__ import annotations
+
+import re
+from datetime import date
+from pathlib import Path
+from urllib.parse import unquote
+
+import yaml
+
+from .model import MaintenanceReport
+
+SKIP_PARTS = {
+    ".git",
+    ".tmp",
+    ".venv",
+    ".pytest_cache",
+    ".ruff_cache",
+    "__pycache__",
+    "build",
+    "dist",
+}
+PUBLIC_REPOSITORY_PREFIXES = (
+    "https://github.com/e-south/reader/blob/main/",
+    "https://github.com/e-south/reader/tree/main/",
+)
+LINK_RE = re.compile(r"!?\[[^\]]+\]\(([^)]+)\)")
+HEADING_RE = re.compile(r"^(#{1,6})\s+(.+?)\s*#*\s*$")
+HTML_ANCHOR_RE = re.compile(r"""<a\s+(?:[^>]*?\s)?(?:id|name)=["']([^"']+)["']""", re.IGNORECASE)
+FENCE_RE = re.compile(r"^\s*(```|~~~)")
+DOC_ID_RE = re.compile(r"^[a-z0-9][a-z0-9-]*$")
+REQUIRED_FRONTMATTER_FIELDS = {"doc_id", "surface", "owner", "last_verified", "summary"}
+FRONTMATTER_DOCS = {
+    "ARCHITECTURE.md",
+    "DESIGN.md",
+    "QUALITY.md",
+    "RELIABILITY.md",
+    "SECURITY.md",
+}
+REQUIRED_LINKS = {
+    "README.md": {
+        "docs/README.md",
+        "docs/guides/getting_started.md",
+        "docs/guides/common_routes.md",
+    },
+    "docs/README.md": {
+        "guides/getting_started.md",
+        "guides/common_routes.md",
+        "guides/preflight_run_verify.md",
+        "guides/automation.md",
+        "guides/data_operations_plan.md",
+        "guides/experiment_bootstrap.md",
+        "guides/demo.md",
+        "core/cli.md",
+        "core/pipeline.md",
+        "repo-change-gate.md",
+        "repo-maintenance.md",
+        "../QUALITY.md",
+        "../RELIABILITY.md",
+    },
+    "docs/guides/experiment_bootstrap.md": {
+        "./data_operations_plan.md",
+        "./data_operations_plan/data_classes.md",
+    },
+    "docs/guides/data_operations_plan.md": {
+        "../../src/reader_workbench/workbench/dop/",
+        "../../.agents/skills/reader-data-operations-plan/SKILL.md",
+        "./data_operations_plan/operating_model.md",
+        "./data_operations_plan/data_classes.md",
+        "./data_operations_plan/metadata_minimums.md",
+        "./data_operations_plan/transfer_and_verification.md",
+        "./experiment_bootstrap.md",
+        "./preflight_run_verify.md",
+    },
+    "docs/guides/getting_started.md": {
+        "./package_namespace_migration.md",
+    },
+    "docs/repo-maintenance.md": {
+        "./guides/package_namespace_migration.md",
+    },
+    ".agents/skills/reader-data-operations-plan/SKILL.md": {
+        "../../../docs/guides/data_operations_plan.md",
+        "../../../docs/guides/data_operations_plan/operating_model.md",
+        "../../../docs/guides/experiment_bootstrap.md",
+        "./references/endpoint-contracts.md",
+        "./references/external-sources.md",
+        "./references/test-matrix.md",
+        "./references/workflow.md",
+    },
+    "docs/core/spec.md": {
+        "./pipeline.md",
+        "../../ARCHITECTURE.md",
+        "../../src/reader_workbench/protocols/",
+        "../../src/reader_workbench/workbench/dop/",
+        "../../src/reader_workbench/workbench/experiment/",
+        "../../src/reader_workbench/workbench/engine/",
+        "../../src/reader_workbench/plugins/",
+        "../../src/reader_workbench/contracts/",
+        "../repo-maintenance.md",
+        "../../QUALITY.md",
+        "../../RELIABILITY.md",
+    },
+    "docs/core/plugins.md": {
+        "./pipeline.md",
+        "./spec.md",
+        "../../ARCHITECTURE.md",
+        "../../src/reader_workbench/plugins/",
+        "../../src/reader_workbench/plugins/catalog.py",
+        "../../src/reader_workbench/protocols/compiler.py",
+    },
+}
+
+
+def _is_generated_experiment_output(path: Path, repo_root: Path) -> bool:
+    relative = path.relative_to(repo_root)
+    return bool(relative.parts) and relative.parts[0] == "experiments" and "outputs" in relative.parts
+
+
+def iter_markdown_files(repo_root: Path) -> list[Path]:
+    repo_root = repo_root.resolve()
+    return sorted(
+        path
+        for path in repo_root.rglob("*.md")
+        if not any(part in SKIP_PARTS for part in path.parts) and not _is_generated_experiment_output(path, repo_root)
+    )
+
+
+def iter_navigable_docs(repo_root: Path) -> list[Path]:
+    repo_root = repo_root.resolve()
+    top_level = [repo_root / path for path in sorted(FRONTMATTER_DOCS)]
+    return top_level + sorted((repo_root / "docs").rglob("*.md"))
+
+
+def _frontmatter_payload(path: Path) -> tuple[dict[str, object] | None, str | None]:
+    lines = path.read_text(encoding="utf-8").splitlines()
+    if not lines or lines[0].strip() != "---":
+        return None, "missing opening front matter delimiter"
+    try:
+        closing = next(index for index, line in enumerate(lines[1:], start=1) if line.strip() == "---")
+    except StopIteration:
+        return None, "missing closing front matter delimiter"
+    try:
+        payload = yaml.safe_load("\n".join(lines[1:closing]))
+    except yaml.YAMLError as exc:
+        return None, f"invalid YAML front matter: {exc}"
+    if not isinstance(payload, dict):
+        return None, "front matter must be a YAML mapping"
+    return payload, None
+
+
+def check_doc_frontmatter(files: list[Path], repo_root: Path) -> list[str]:
+    errors: list[str] = []
+    seen_ids: dict[str, Path] = {}
+    for path in files:
+        rel_path = path.relative_to(repo_root)
+        payload, parse_error = _frontmatter_payload(path)
+        if parse_error is not None:
+            errors.append(f"front matter: {rel_path}: {parse_error}")
+            continue
+        assert payload is not None
+        missing = sorted(REQUIRED_FRONTMATTER_FIELDS - set(payload))
+        if missing:
+            errors.append(f"front matter: {rel_path}: missing fields {missing}")
+            continue
+        for field in ("doc_id", "surface", "owner", "summary"):
+            value = payload[field]
+            if not isinstance(value, str) or not value.strip():
+                errors.append(f"front matter: {rel_path}: {field} must be a non-empty string")
+        summary = payload["summary"]
+        if isinstance(summary, str) and len(summary.strip()) > 200:
+            errors.append(f"front matter: {rel_path}: summary must be at most 200 characters")
+        doc_id = payload["doc_id"]
+        if isinstance(doc_id, str) and doc_id.strip():
+            if DOC_ID_RE.fullmatch(doc_id) is None:
+                errors.append(f"front matter: {rel_path}: invalid doc_id {doc_id!r}")
+            previous = seen_ids.get(doc_id)
+            if previous is not None:
+                errors.append(
+                    f"front matter: {rel_path}: duplicate doc_id {doc_id!r} also used by {previous.relative_to(repo_root)}"
+                )
+            else:
+                seen_ids[doc_id] = path
+        verified_raw = payload["last_verified"]
+        if isinstance(verified_raw, date):
+            verified = verified_raw
+        elif not isinstance(verified_raw, str):
+            errors.append(f"front matter: {rel_path}: last_verified must be an ISO date")
+            continue
+        else:
+            try:
+                verified = date.fromisoformat(verified_raw)
+            except ValueError:
+                errors.append(f"front matter: {rel_path}: last_verified must be an ISO date")
+                continue
+        age_days = (date.today() - verified).days
+        if age_days < 0:
+            errors.append(f"front matter: {rel_path}: last_verified must not be in the future")
+        elif age_days > 365:
+            errors.append(f"front matter: {rel_path}: last_verified is stale ({age_days} days old)")
+    return errors
+
+
+def normalize_target(source: Path, raw_target: str, *, repo_root: Path | None = None) -> Path | None:
+    target = raw_target.strip().split(" ", 1)[0]
+    for prefix in PUBLIC_REPOSITORY_PREFIXES:
+        if target.startswith(prefix):
+            if repo_root is None:
+                return None
+            relative_target = target.removeprefix(prefix).split("#", 1)[0]
+            return (repo_root / relative_target).resolve()
+    if target.startswith(("http://", "https://", "mailto:", "#")):
+        return None
+    target = target.split("#", 1)[0]
+    if not target:
+        return None
+    return (source.parent / target).resolve()
+
+
+def normalize_anchor_target(source: Path, raw_target: str) -> tuple[Path, str] | None:
+    target = raw_target.strip().split(" ", 1)[0]
+    if target.startswith(("http://", "https://", "mailto:")) or "#" not in target:
+        return None
+    path_raw, anchor_raw = target.split("#", 1)
+    anchor = unquote(anchor_raw).strip()
+    if not anchor:
+        return None
+    target_path = source if not path_raw else (source.parent / path_raw).resolve()
+    if target_path.suffix.lower() != ".md":
+        return None
+    return target_path, anchor
+
+
+def markdown_anchors(source: Path) -> set[str]:
+    anchors: set[str] = set()
+    slug_counts: dict[str, int] = {}
+    in_fence = False
+    for line in source.read_text().splitlines():
+        if FENCE_RE.match(line):
+            in_fence = not in_fence
+            continue
+        if in_fence:
+            continue
+        for explicit_anchor in HTML_ANCHOR_RE.findall(line):
+            anchors.add(explicit_anchor)
+        heading = HEADING_RE.match(line)
+        if heading is None:
+            continue
+        slug = github_heading_slug(heading.group(2))
+        count = slug_counts.get(slug, 0)
+        anchors.add(slug if count == 0 else f"{slug}-{count}")
+        slug_counts[slug] = count + 1
+    return anchors
+
+
+def github_heading_slug(text: str) -> str:
+    text = re.sub(r"`([^`]*)`", r"\1", text)
+    text = re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", text)
+    text = re.sub(r"<[^>]+>", "", text)
+    text = text.strip().lower()
+    text = re.sub(r"[^\w\s-]", "", text)
+    text = re.sub(r"\s+", "-", text)
+    return re.sub(r"-+", "-", text).strip("-")
+
+
+def linked_paths(source: Path, *, repo_root: Path | None = None) -> set[Path]:
+    linked: set[Path] = set()
+    for raw_target in LINK_RE.findall(source.read_text()):
+        normalized = normalize_target(source, raw_target, repo_root=repo_root)
+        if normalized is not None:
+            linked.add(normalized)
+    return linked
+
+
+def check_internal_links(files: list[Path], repo_root: Path) -> list[str]:
+    errors: list[str] = []
+    for file in files:
+        for raw_target in LINK_RE.findall(file.read_text()):
+            normalized = normalize_target(file, raw_target, repo_root=repo_root)
+            if normalized is None:
+                continue
+            rel_file = file.relative_to(repo_root)
+            if not normalized.is_relative_to(repo_root):
+                errors.append(f"link escapes repository: {rel_file} -> {raw_target}")
+                continue
+            if not normalized.exists():
+                errors.append(f"broken link: {rel_file} -> {raw_target}")
+    return errors
+
+
+def check_markdown_anchors(files: list[Path], repo_root: Path) -> list[str]:
+    anchors_by_file = {file.resolve(): markdown_anchors(file) for file in files}
+    errors: list[str] = []
+    for file in files:
+        for raw_target in LINK_RE.findall(file.read_text()):
+            normalized = normalize_anchor_target(file, raw_target)
+            if normalized is None:
+                continue
+            target_file, anchor = normalized
+            if not target_file.exists():
+                continue
+            anchors = anchors_by_file.get(target_file.resolve())
+            if anchors is None:
+                continue
+            if anchor not in anchors:
+                rel_file = file.relative_to(repo_root)
+                errors.append(f"broken anchor: {rel_file} -> {raw_target}")
+    return errors
+
+
+def check_required_routes(repo_root: Path) -> list[str]:
+    errors: list[str] = []
+    for rel_source, rel_targets in REQUIRED_LINKS.items():
+        source = repo_root / rel_source
+        linked = linked_paths(source, repo_root=repo_root)
+        for rel_target in sorted(rel_targets):
+            expected = (source.parent / rel_target).resolve()
+            if expected not in linked:
+                errors.append(f"missing required route: {rel_source} -> {rel_target}")
+    return errors
+
+
+def check_docs(repo_root: Path) -> MaintenanceReport:
+    """Check documentation integrity in a Reader source checkout."""
+
+    repo_root = repo_root.resolve()
+    files = iter_markdown_files(repo_root)
+    errors = check_internal_links(files, repo_root)
+    errors.extend(check_markdown_anchors(files, repo_root))
+    errors.extend(check_required_routes(repo_root))
+    errors.extend(check_doc_frontmatter(iter_navigable_docs(repo_root), repo_root))
+    return MaintenanceReport(
+        check="docs",
+        repo_root=repo_root,
+        checked=len(files),
+        errors=tuple(errors),
+    )

reader_workbench/maintenance/model.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True, slots=True)
+class MaintenanceReport:
+    """Typed result from a repository-maintenance check."""
+
+    check: str
+    repo_root: Path
+    checked: int
+    errors: tuple[str, ...]
+
+    @property
+    def ok(self) -> bool:
+        return not self.errors
+
+    def to_payload(self) -> dict[str, object]:
+        return {
+            "schema": "reader.maintenance/v1",
+            "check": self.check,
+            "status": "ok" if self.ok else "failed",
+            "repo_root": str(self.repo_root),
+            "checked": self.checked,
+            "errors": list(self.errors),
+        }

reader_workbench/maintenance/release.py

@@ -0,0 +1,39 @@
+"""Fail closed unless a release commit passed the canonical main-push checks."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any
+
+
+def require_successful_checks(payload: dict[str, Any], revision: str) -> dict[str, Any]:
+    """Return the latest qualifying CI run; an older success cannot mask a failure."""
+    runs = [
+        run
+        for run in payload["workflow_runs"]
+        if run.get("head_sha") == revision
+        and run.get("event") == "push"
+        and run.get("head_branch") == "main"
+        and run.get("path") == ".github/workflows/checks.yaml"
+        and (run.get("head_repository") or {}).get("full_name") == "e-south/reader"
+    ]
+    if not runs:
+        raise ValueError("No canonical main-push Checks run for the release commit")
+    latest = max(runs, key=lambda run: int(run["id"]))
+    if latest.get("status") != "completed" or latest.get("conclusion") != "success":
+        raise ValueError("The latest main-push Checks run has not completed successfully")
+    return latest
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--checks", type=Path, required=True)
+    parser.add_argument("--revision", required=True)
+    args = parser.parse_args()
+    print(json.dumps(require_successful_checks(json.loads(args.checks.read_text()), args.revision), indent=2))
+
+
+if __name__ == "__main__":
+    main()

reader_workbench/maintenance/skills.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from .model import MaintenanceReport
+
+FRONTMATTER_RE = re.compile(r"\A---\n(.*?)\n---\n", re.DOTALL)
+SOURCE_ROW_RE = re.compile(r"^\| https?://[^|]+ \| \d{4}-\d{2}-\d{2} \| [^|]+ \|$", re.MULTILINE)
+SKILLS_RELATIVE_ROOT = Path(".agents") / "skills"
+
+
+def iter_skill_dirs(skills_dir: Path) -> list[Path]:
+    return sorted(path for path in skills_dir.iterdir() if path.is_dir() and not path.name.startswith("."))
+
+
+def read_text(path: Path) -> str:
+    return path.read_text(encoding="utf-8")
+
+
+def frontmatter_block(text: str, skill_path: Path, repo_root: Path) -> str:
+    match = FRONTMATTER_RE.match(text)
+    if match is None:
+        raise ValueError(f"{skill_path.relative_to(repo_root)}: missing frontmatter")
+    return match.group(1)
+
+
+def require_in_block(block: str, needle: str, skill_path: Path, label: str, repo_root: Path) -> list[str]:
+    if needle not in block:
+        return [f"{skill_path.relative_to(repo_root)}: missing {label}"]
+    return []
+
+
+def audit_skill_dir(skill_dir: Path, repo_root: Path) -> list[str]:
+    errors: list[str] = []
+    skill_path = skill_dir / "SKILL.md"
+    if not skill_path.exists():
+        return [f"{skill_dir.relative_to(repo_root)}: missing SKILL.md"]
+
+    text = read_text(skill_path)
+    try:
+        frontmatter = frontmatter_block(text, skill_path, repo_root)
+    except ValueError as exc:
+        return [str(exc)]
+
+    errors.extend(
+        require_in_block(
+            frontmatter,
+            f"name: {skill_dir.name}",
+            skill_path,
+            "frontmatter name matching folder",
+            repo_root,
+        )
+    )
+    errors.extend(require_in_block(frontmatter, "description:", skill_path, "frontmatter description", repo_root))
+    errors.extend(require_in_block(frontmatter, "metadata:", skill_path, "metadata block", repo_root))
+    errors.extend(require_in_block(frontmatter, "version:", skill_path, "metadata.version", repo_root))
+    errors.extend(require_in_block(frontmatter, "category:", skill_path, "metadata.category", repo_root))
+    errors.extend(require_in_block(frontmatter, "tags:", skill_path, "metadata.tags", repo_root))
+
+    if "Use when" not in frontmatter or "Do not use" not in frontmatter:
+        errors.append(
+            f"{skill_path.relative_to(repo_root)}: frontmatter description must include "
+            "'Use when' and 'Do not use' routing boundaries"
+        )
+
+    required_sections = [
+        "## Purpose",
+        "## Scope",
+        "## Required Deliverables",
+        "## Output Contract",
+        "## Trigger Tests",
+    ]
+    for section in required_sections:
+        if section not in text:
+            errors.append(f"{skill_path.relative_to(repo_root)}: missing section {section}")
+
+    external_sources_path = skill_dir / "references" / "external-sources.md"
+    if not external_sources_path.exists():
+        errors.append(f"{skill_dir.relative_to(repo_root)}: missing references/external-sources.md")
+    elif "./references/external-sources.md" not in text:
+        errors.append(
+            f"{skill_path.relative_to(repo_root)}: top-level skill does not expose references/external-sources.md"
+        )
+    else:
+        external_sources = read_text(external_sources_path)
+        if "| URL | Retrieved | Mapped update |" not in external_sources:
+            errors.append(
+                f"{external_sources_path.relative_to(repo_root)}: missing source table header "
+                "'| URL | Retrieved | Mapped update |'"
+            )
+        if SOURCE_ROW_RE.search(external_sources) is None:
+            errors.append(
+                f"{external_sources_path.relative_to(repo_root)}: missing at least one source row "
+                "with URL, YYYY-MM-DD retrieved date, and mapped update"
+            )
+
+    return errors
+
+
+def check_skills(repo_root: Path) -> MaintenanceReport:
+    """Check repo-local skill structure in a Reader source checkout."""
+
+    repo_root = repo_root.resolve()
+    skills_dir = repo_root / SKILLS_RELATIVE_ROOT
+    if not skills_dir.is_dir():
+        return MaintenanceReport(
+            check="skills",
+            repo_root=repo_root,
+            checked=0,
+            errors=(f"{SKILLS_RELATIVE_ROOT.as_posix()} directory missing",),
+        )
+
+    errors: list[str] = []
+    skill_dirs = iter_skill_dirs(skills_dir)
+    for skill_dir in skill_dirs:
+        errors.extend(audit_skill_dir(skill_dir, repo_root))
+
+    return MaintenanceReport(
+        check="skills",
+        repo_root=repo_root,
+        checked=len(skill_dirs),
+        errors=tuple(errors),
+    )

reader_workbench/plotting/__init__.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import importlib
+
+_EXPORTS = {
+    "mpl": {"ensure_mpl_cache_dir"},
+    "sinks": {"PlotFigure", "normalize_plot_figures", "save_plot_figures"},
+    "style": {"DEFAULT_RC", "PaletteBook", "available_palettes", "new_fig_ax", "use_style"},
+    "utils": {"ensure_dir", "save_figure", "slugify"},
+}
+
+__all__ = tuple(sorted({name for names in _EXPORTS.values() for name in names}))
+
+
+def __getattr__(name: str):
+    for module_name, names in _EXPORTS.items():
+        if name in names:
+            module = importlib.import_module(f"reader_workbench.plotting.{module_name}")
+            return getattr(module, name)
+    raise AttributeError(name)

reader_workbench/plotting/mpl.py

@@ -0,0 +1,56 @@
+"""Matplotlib cache handling."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from reader_workbench.errors import ConfigError
+
+
+def _find_repo_root() -> Path | None:
+    here = Path(__file__).resolve()
+    for parent in here.parents:
+        if (parent / "pyproject.toml").exists():
+            return parent
+    return None
+
+
+def _default_cache_dir(base_dir: Path | None) -> Path:
+    if base_dir is not None:
+        return Path(base_dir).expanduser().resolve() / ".cache" / "matplotlib"
+    repo_root = _find_repo_root()
+    if repo_root is not None:
+        return repo_root / ".cache" / "matplotlib"
+    xdg = os.environ.get("XDG_CACHE_HOME")
+    if xdg:
+        return Path(xdg).expanduser().resolve() / "reader" / "matplotlib"
+    return Path.home() / ".cache" / "reader" / "matplotlib"
+
+
+def ensure_mpl_cache_dir(*, base_dir: Path | None = None) -> Path:
+    """
+    Ensure MPLCONFIGDIR points to a writable directory.
+
+    Priority:
+      1) MPLCONFIGDIR (if set)
+      2) READER_MPLCONFIGDIR (if set)
+      3) base_dir/.cache/matplotlib (if base_dir provided)
+      4) <repo>/.cache/matplotlib (if running from a reader checkout)
+      5) $XDG_CACHE_HOME/reader/matplotlib or ~/.cache/reader/matplotlib
+    """
+    env = os.environ.get("MPLCONFIGDIR") or os.environ.get("READER_MPLCONFIGDIR")
+    cache_dir = Path(env).expanduser() if env else _default_cache_dir(base_dir)
+
+    if cache_dir.exists() and not cache_dir.is_dir():
+        raise ConfigError(f"Matplotlib cache path is not a directory: {cache_dir}")
+    try:
+        cache_dir.mkdir(parents=True, exist_ok=True)
+    except Exception as exc:
+        raise ConfigError(
+            "Matplotlib cache directory is not writable. "
+            f"Set MPLCONFIGDIR or READER_MPLCONFIGDIR to a writable path (current: {cache_dir})."
+        ) from exc
+
+    os.environ["MPLCONFIGDIR"] = str(cache_dir)
+    return cache_dir

reader_workbench/plotting/sinks.py

@@ -0,0 +1,69 @@
+"""Plot sinks for saving rendered figures."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from contextlib import suppress
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from reader_workbench.errors import ExecutionError
+from reader_workbench.plotting.utils import save_figure
+
+
+@dataclass(frozen=True)
+class PlotFigure:
+    fig: Any
+    filename: str
+    ext: str = "pdf"
+    dpi: int | None = None
+    description: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.description is None:
+            return
+        if not isinstance(self.description, str) or not self.description.strip():
+            raise ExecutionError("PlotFigure.description must be a non-empty string when provided")
+        normalized = self.description.strip()
+        if "\n" in normalized or "\r" in normalized:
+            raise ExecutionError("PlotFigure.description must be a single line")
+        object.__setattr__(self, "description", normalized)
+
+
+def normalize_plot_figures(rendered: Any, *, where: str) -> list[PlotFigure]:
+    if rendered is None:
+        return []
+    if isinstance(rendered, PlotFigure):
+        return [rendered]
+    if isinstance(rendered, Iterable) and not isinstance(rendered, str | bytes):
+        figures: list[PlotFigure] = []
+        for item in rendered:
+            if not isinstance(item, PlotFigure):
+                raise ExecutionError(f"{where}: render must return PlotFigure objects, got {type(item).__name__}")
+            figures.append(item)
+        return figures
+    raise ExecutionError(f"{where}: render must return PlotFigure or list[PlotFigure], got {type(rendered).__name__}")
+
+
+def save_plot_figures(figures: list[PlotFigure], output_dir: Path) -> list[Path]:
+    saved: list[Path] = []
+    if not figures:
+        return saved
+    try:
+        import matplotlib.pyplot as plt  # noqa: PLC0415
+    except Exception as exc:  # pragma: no cover - dependency guard
+        raise ExecutionError("Plot saving requires matplotlib.") from exc
+    seen_figs: list[Any] = []
+    for item in figures:
+        ext = str(item.ext or "pdf").lstrip(".").lower()
+        if not item.filename or not str(item.filename).strip():
+            raise ExecutionError("PlotFigure.filename must be a non-empty string")
+        path = save_figure(item.fig, output_dir, str(item.filename), ext=ext, dpi=item.dpi)
+        saved.append(path)
+        if item.fig not in seen_figs:
+            seen_figs.append(item.fig)
+    for fig in seen_figs:
+        with suppress(Exception):
+            plt.close(fig)
+    return saved