PPTX Posters

scripts/_manifest.py

#!/usr/bin/env python3
"""Strict poster-manifest validation shared by generation and audit tools."""

from __future__ import annotations

import re
from pathlib import Path
from typing import Any

from _common import (
    PPTX_MAX_INCHES,
    PPTX_MIN_INCHES,
    CliError,
    canonical_json_hash,
    contrast_ratio,
    finite_number,
    has_placeholder,
    load_json_file,
    parse_aware_datetime,
    parse_hex_color,
    positive_int,
    reject_unknown_keys,
    require_bool,
    require_string,
    resolve_local_asset,
    sha256_file,
)

MANIFEST_SCHEMA_VERSION = "2.0"
REPORT_SCHEMA_VERSION = "1.0"
MAX_ELEMENTS = 250
MAX_SOURCES = 500
MAX_ASSETS = 100
ASSET_SUFFIXES = {".png", ".jpg", ".jpeg"}

_ID = re.compile(r"^[A-Za-z][A-Za-z0-9_.-]{0,63}$")
_SHA256 = re.compile(r"^[0-9a-f]{64}$")
_RELATIVE_PATH = re.compile(r"^[^:/\\][^:\\]*$")

_TOP_KEYS = {
    "schema_version",
    "document",
    "canvas",
    "physical_output",
    "requirements",
    "quality",
    "palette",
    "sources",
    "assets",
    "elements",
    "approval",
}
_SOURCE_KINDS = {
    "author_content",
    "publication",
    "dataset",
    "asset_license",
    "conference_rule",
    "printer_rule",
    "institutional_rule",
    "other",
}
_FONT_BASES = {
    "heuristic",
    "source_specific",
    "conference_requirement",
    "printer_requirement",
}
_TEXT_ROLES = {
    "title",
    "authors",
    "affiliation",
    "heading",
    "body",
    "caption",
    "reference",
    "acknowledgement",
    "contact",
    "qr_fallback",
    "other",
}


def _identifier(value: Any, *, context: str) -> str:
    text = require_string(value, context=context, maximum=64)
    if not _ID.fullmatch(text):
        raise CliError(
            f"{context} must start with a letter and contain only letters, "
            "digits, period, underscore, or hyphen"
        )
    return text


def _nullable_source_id(value: Any, *, context: str) -> str | None:
    if value is None:
        return None
    return _identifier(value, context=context)


def _string_list(
    value: Any,
    *,
    context: str,
    minimum: int,
    maximum: int,
) -> list[str]:
    if not isinstance(value, list):
        raise CliError(f"{context} must be an array")
    if not minimum <= len(value) <= maximum:
        raise CliError(
            f"{context} must contain between {minimum} and {maximum} values"
        )
    result = [
        require_string(item, context=f"{context}[{index}]", maximum=500)
        for index, item in enumerate(value)
    ]
    if len(set(result)) != len(result):
        raise CliError(f"{context} must not contain duplicates")
    return result


def _source_id_list(value: Any, *, context: str) -> list[str]:
    raw = _string_list(value, context=context, minimum=1, maximum=16)
    return [
        _identifier(item, context=f"{context}[{index}]")
        for index, item in enumerate(raw)
    ]


def manifest_content_hash(document: dict[str, Any]) -> str:
    """Hash all author-controlled manifest content except the approval record."""
    return canonical_json_hash(
        {key: value for key, value in document.items() if key != "approval"}
    )


def _validate_document(value: Any) -> dict[str, Any]:
    document = reject_unknown_keys(
        value,
        context="document",
        allowed={"id", "title", "subject", "language", "authors", "source_ids"},
        required={"id", "title", "subject", "language", "authors", "source_ids"},
    )
    _identifier(document["id"], context="document.id")
    require_string(document["title"], context="document.title", maximum=500)
    require_string(document["subject"], context="document.subject", maximum=1_000)
    language = require_string(
        document["language"], context="document.language", maximum=35
    )
    if not re.fullmatch(r"[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*", language):
        raise CliError("document.language must be a BCP 47-style language tag")
    _string_list(
        document["authors"],
        context="document.authors",
        minimum=1,
        maximum=50,
    )
    _source_id_list(document["source_ids"], context="document.source_ids")
    return document


def _validate_canvas(value: Any) -> tuple[dict[str, Any], float, float]:
    canvas = reject_unknown_keys(
        value,
        context="canvas",
        allowed={"width_in", "height_in", "background_color"},
        required={"width_in", "height_in", "background_color"},
    )
    width = finite_number(
        canvas["width_in"],
        context="canvas.width_in",
        minimum=PPTX_MIN_INCHES,
        maximum=PPTX_MAX_INCHES,
    )
    height = finite_number(
        canvas["height_in"],
        context="canvas.height_in",
        minimum=PPTX_MIN_INCHES,
        maximum=PPTX_MAX_INCHES,
    )
    parse_hex_color(canvas["background_color"], context="canvas.background_color")
    return canvas, width, height


def _validate_physical_output(
    value: Any,
) -> tuple[dict[str, Any], float, float, float, float, float, float]:
    physical = reject_unknown_keys(
        value,
        context="physical_output",
        allowed={
            "trim_width_in",
            "trim_height_in",
            "bleed_in",
            "safe_margin_in",
            "orientation",
        },
        required={
            "trim_width_in",
            "trim_height_in",
            "bleed_in",
            "safe_margin_in",
            "orientation",
        },
    )
    trim_width = finite_number(
        physical["trim_width_in"],
        context="physical_output.trim_width_in",
        minimum=1.0,
        maximum=200.0,
    )
    trim_height = finite_number(
        physical["trim_height_in"],
        context="physical_output.trim_height_in",
        minimum=1.0,
        maximum=200.0,
    )
    bleed = finite_number(
        physical["bleed_in"],
        context="physical_output.bleed_in",
        minimum=0.0,
        maximum=2.0,
    )
    safe_margin = finite_number(
        physical["safe_margin_in"],
        context="physical_output.safe_margin_in",
        minimum=0.0,
        maximum=10.0,
    )
    if 2 * safe_margin >= min(trim_width, trim_height):
        raise CliError("physical_output.safe_margin_in consumes the trim area")
    orientation = require_string(
        physical["orientation"],
        context="physical_output.orientation",
        maximum=16,
    )
    expected = (
        "square"
        if abs(trim_width - trim_height) <= 1e-6
        else ("landscape" if trim_width > trim_height else "portrait")
    )
    if orientation != expected:
        raise CliError(
            "physical_output.orientation does not match the trim dimensions "
            f"(expected {expected!r})"
        )
    artboard_width = trim_width + 2 * bleed
    artboard_height = trim_height + 2 * bleed
    return (
        physical,
        trim_width,
        trim_height,
        bleed,
        safe_margin,
        artboard_width,
        artboard_height,
    )


def _validate_sources(value: Any) -> dict[str, dict[str, Any]]:
    if not isinstance(value, list) or not 1 <= len(value) <= MAX_SOURCES:
        raise CliError(f"sources must contain between 1 and {MAX_SOURCES} objects")
    result: dict[str, dict[str, Any]] = {}
    for index, item in enumerate(value):
        context = f"sources[{index}]"
        source = reject_unknown_keys(
            item,
            context=context,
            allowed={"id", "kind", "citation", "locator", "author_verified"},
            required={"id", "kind", "citation", "locator", "author_verified"},
        )
        source_id = _identifier(source["id"], context=f"{context}.id")
        if source_id in result:
            raise CliError(f"duplicate source id: {source_id}")
        kind = require_string(source["kind"], context=f"{context}.kind", maximum=32)
        if kind not in _SOURCE_KINDS:
            raise CliError(
                f"{context}.kind must be one of {', '.join(sorted(_SOURCE_KINDS))}"
            )
        require_string(
            source["citation"], context=f"{context}.citation", maximum=2_000
        )
        require_string(source["locator"], context=f"{context}.locator", maximum=2_000)
        if not require_bool(
            source["author_verified"], context=f"{context}.author_verified"
        ):
            raise CliError(f"{context}.author_verified must be true")
        result[source_id] = source
    return result


def _validate_requirements(
    value: Any,
    *,
    trim_width: float,
    trim_height: float,
    bleed: float,
    safe_margin: float,
    print_scale: float,
) -> tuple[dict[str, Any], set[str]]:
    requirements = reject_unknown_keys(
        value,
        context="requirements",
        allowed={"conference", "printer"},
        required={"conference", "printer"},
    )
    conference = reject_unknown_keys(
        requirements["conference"],
        context="requirements.conference",
        allowed={
            "confirmed",
            "source_id",
            "max_width_in",
            "max_height_in",
            "orientation",
            "required_delivery_format",
            "notes",
        },
        required={
            "confirmed",
            "source_id",
            "max_width_in",
            "max_height_in",
            "orientation",
            "required_delivery_format",
            "notes",
        },
    )
    if not require_bool(
        conference["confirmed"], context="requirements.conference.confirmed"
    ):
        raise CliError("requirements.conference.confirmed must be true")
    conference_source = _identifier(
        conference["source_id"], context="requirements.conference.source_id"
    )
    max_width = finite_number(
        conference["max_width_in"],
        context="requirements.conference.max_width_in",
        minimum=1.0,
        maximum=200.0,
    )
    max_height = finite_number(
        conference["max_height_in"],
        context="requirements.conference.max_height_in",
        minimum=1.0,
        maximum=200.0,
    )
    conference_orientation = require_string(
        conference["orientation"],
        context="requirements.conference.orientation",
        maximum=16,
    )
    if conference_orientation not in {"portrait", "landscape", "square", "either"}:
        raise CliError(
            "requirements.conference.orientation must be portrait, landscape, "
            "square, or either"
        )
    physical_orientation = (
        "square"
        if abs(trim_width - trim_height) <= 1e-6
        else ("landscape" if trim_width > trim_height else "portrait")
    )
    if (
        conference_orientation != "either"
        and conference_orientation != physical_orientation
    ):
        raise CliError("physical output violates the confirmed conference orientation")
    if trim_width > max_width + 1e-6 or trim_height > max_height + 1e-6:
        raise CliError("physical output exceeds the confirmed conference dimensions")
    delivery = require_string(
        conference["required_delivery_format"],
        context="requirements.conference.required_delivery_format",
        maximum=32,
    )
    if delivery not in {"PDF", "PPTX", "PDF_AND_PPTX", "OTHER"}:
        raise CliError(
            "requirements.conference.required_delivery_format must be PDF, PPTX, "
            "PDF_AND_PPTX, or OTHER"
        )
    require_string(
        conference["notes"],
        context="requirements.conference.notes",
        minimum=0,
        maximum=2_000,
    )

    printer = reject_unknown_keys(
        requirements["printer"],
        context="requirements.printer",
        allowed={
            "confirmed",
            "source_id",
            "trim_width_in",
            "trim_height_in",
            "bleed_in",
            "safe_margin_in",
            "accepted_color_mode",
            "scaling_allowed",
            "notes",
        },
        required={
            "confirmed",
            "source_id",
            "trim_width_in",
            "trim_height_in",
            "bleed_in",
            "safe_margin_in",
            "accepted_color_mode",
            "scaling_allowed",
            "notes",
        },
    )
    if not require_bool(printer["confirmed"], context="requirements.printer.confirmed"):
        raise CliError("requirements.printer.confirmed must be true")
    printer_source = _identifier(
        printer["source_id"], context="requirements.printer.source_id"
    )
    printer_trim_width = finite_number(
        printer["trim_width_in"],
        context="requirements.printer.trim_width_in",
        minimum=1.0,
        maximum=200.0,
    )
    printer_trim_height = finite_number(
        printer["trim_height_in"],
        context="requirements.printer.trim_height_in",
        minimum=1.0,
        maximum=200.0,
    )
    printer_bleed = finite_number(
        printer["bleed_in"],
        context="requirements.printer.bleed_in",
        minimum=0.0,
        maximum=2.0,
    )
    printer_margin = finite_number(
        printer["safe_margin_in"],
        context="requirements.printer.safe_margin_in",
        minimum=0.0,
        maximum=10.0,
    )
    for actual, required, label in (
        (trim_width, printer_trim_width, "trim width"),
        (trim_height, printer_trim_height, "trim height"),
        (bleed, printer_bleed, "bleed"),
        (safe_margin, printer_margin, "safe margin"),
    ):
        if abs(actual - required) > 1e-6:
            raise CliError(
                f"physical output {label} does not match the confirmed printer rule"
            )
    color_mode = require_string(
        printer["accepted_color_mode"],
        context="requirements.printer.accepted_color_mode",
        maximum=32,
    )
    if color_mode not in {"RGB", "CMYK", "PRINTER_MANAGED"}:
        raise CliError(
            "requirements.printer.accepted_color_mode must be RGB, CMYK, "
            "or PRINTER_MANAGED"
        )
    scaling_allowed = require_bool(
        printer["scaling_allowed"], context="requirements.printer.scaling_allowed"
    )
    if not scaling_allowed and abs(print_scale - 1.0) > 1e-6:
        raise CliError(
            "printer forbids scaling but canvas and physical artboard differ"
        )
    require_string(
        printer["notes"],
        context="requirements.printer.notes",
        minimum=0,
        maximum=2_000,
    )
    return requirements, {conference_source, printer_source}


def _validate_quality(value: Any) -> tuple[dict[str, Any], set[str]]:
    quality = reject_unknown_keys(
        value,
        context="quality",
        allowed={
            "minimum_font_pt_final",
            "font_guidance_basis",
            "font_guidance_source_id",
            "minimum_raster_dpi_final",
            "raster_dpi_basis",
            "raster_dpi_source_id",
        },
        required={
            "minimum_font_pt_final",
            "font_guidance_basis",
            "font_guidance_source_id",
            "minimum_raster_dpi_final",
            "raster_dpi_basis",
            "raster_dpi_source_id",
        },
    )
    finite_number(
        quality["minimum_font_pt_final"],
        context="quality.minimum_font_pt_final",
        minimum=1.0,
        maximum=200.0,
    )
    finite_number(
        quality["minimum_raster_dpi_final"],
        context="quality.minimum_raster_dpi_final",
        minimum=1.0,
        maximum=2_400.0,
    )
    used: set[str] = set()
    for prefix in ("font_guidance", "raster_dpi"):
        basis = require_string(
            quality[f"{prefix}_basis"],
            context=f"quality.{prefix}_basis",
            maximum=32,
        )
        if basis not in _FONT_BASES:
            raise CliError(
                f"quality.{prefix}_basis must be one of "
                f"{', '.join(sorted(_FONT_BASES))}"
            )
        source_id = _nullable_source_id(
            quality[f"{prefix}_source_id"],
            context=f"quality.{prefix}_source_id",
        )
        if basis == "heuristic" and source_id is not None:
            raise CliError(
                f"quality.{prefix}_source_id must be null when basis is heuristic"
            )
        if basis != "heuristic" and source_id is None:
            raise CliError(
                f"quality.{prefix}_source_id is required for basis {basis!r}"
            )
        if source_id is not None:
            used.add(source_id)
    return quality, used


def _validate_palette(
    value: Any,
    *,
    enforce_thresholds: bool = True,
) -> tuple[dict[str, Any], dict[str, str], dict[str, dict[str, Any]]]:
    palette = reject_unknown_keys(
        value,
        context="palette",
        allowed={"colors", "contrast_pairs", "data_series_redundant_encoding"},
        required={"colors", "contrast_pairs", "data_series_redundant_encoding"},
    )
    raw_colors = palette["colors"]
    if not isinstance(raw_colors, dict) or not 2 <= len(raw_colors) <= 64:
        raise CliError("palette.colors must contain between 2 and 64 named colors")
    colors: dict[str, str] = {}
    for raw_id, value in raw_colors.items():
        color_id = _identifier(raw_id, context=f"palette.colors[{raw_id!r}]")
        colors[color_id] = parse_hex_color(
            value, context=f"palette.colors.{color_id}"
        )

    raw_pairs = palette["contrast_pairs"]
    if not isinstance(raw_pairs, list) or not 1 <= len(raw_pairs) <= 128:
        raise CliError("palette.contrast_pairs must contain between 1 and 128 pairs")
    pairs: dict[str, dict[str, Any]] = {}
    for index, item in enumerate(raw_pairs):
        context = f"palette.contrast_pairs[{index}]"
        pair = reject_unknown_keys(
            item,
            context=context,
            allowed={
                "id",
                "foreground_color_id",
                "background_color_id",
                "usage",
            },
            required={
                "id",
                "foreground_color_id",
                "background_color_id",
                "usage",
            },
        )
        pair_id = _identifier(pair["id"], context=f"{context}.id")
        if pair_id in pairs:
            raise CliError(f"duplicate contrast pair id: {pair_id}")
        foreground_id = _identifier(
            pair["foreground_color_id"],
            context=f"{context}.foreground_color_id",
        )
        background_id = _identifier(
            pair["background_color_id"],
            context=f"{context}.background_color_id",
        )
        if foreground_id not in colors or background_id not in colors:
            raise CliError(f"{context} references an unknown palette color")
        usage = require_string(pair["usage"], context=f"{context}.usage", maximum=24)
        thresholds = {"normal_text": 4.5, "large_text": 3.0, "non_text": 3.0}
        if usage not in thresholds:
            raise CliError(
                f"{context}.usage must be normal_text, large_text, or non_text"
            )
        ratio = contrast_ratio(colors[foreground_id], colors[background_id])
        if enforce_thresholds and ratio + 1e-9 < thresholds[usage]:
            raise CliError(
                f"{context} contrast is {ratio:.2f}:1, below the "
                f"{thresholds[usage]:.1f}:1 threshold for {usage}"
            )
        pairs[pair_id] = pair
    if not require_bool(
        palette["data_series_redundant_encoding"],
        context="palette.data_series_redundant_encoding",
    ):
        raise CliError("palette.data_series_redundant_encoding must be true")
    return palette, colors, pairs


def _validate_asset_path_syntax(value: Any, *, context: str) -> str:
    path = require_string(value, context=context, maximum=512)
    if not _RELATIVE_PATH.fullmatch(path) or path.startswith(("/", "\\")):
        raise CliError(f"{context} must be a relative local path")
    if "\\" in path or any(part in {"", ".", ".."} for part in Path(path).parts):
        raise CliError(f"{context} contains an unsafe path segment")
    if Path(path).suffix.lower() not in ASSET_SUFFIXES:
        raise CliError(
            f"{context} must use one of {', '.join(sorted(ASSET_SUFFIXES))}"
        )
    return path


def _validate_assets(
    value: Any,
    *,
    manifest_path: Path,
    verify_assets: bool,
) -> tuple[dict[str, dict[str, Any]], dict[str, Path], set[str]]:
    if not isinstance(value, list) or len(value) > MAX_ASSETS:
        raise CliError(f"assets must be an array with at most {MAX_ASSETS} objects")
    assets: dict[str, dict[str, Any]] = {}
    paths: dict[str, Path] = {}
    used_sources: set[str] = set()
    used_path_values: set[str] = set()
    for index, item in enumerate(value):
        context = f"assets[{index}]"
        asset = reject_unknown_keys(
            item,
            context=context,
            allowed={
                "id",
                "path",
                "role",
                "sha256",
                "source_id",
                "license",
                "provenance",
                "alt_text",
                "author_approved",
                "qr_target",
            },
            required={
                "id",
                "path",
                "role",
                "sha256",
                "source_id",
                "license",
                "provenance",
                "alt_text",
                "author_approved",
                "qr_target",
            },
        )
        asset_id = _identifier(asset["id"], context=f"{context}.id")
        if asset_id in assets:
            raise CliError(f"duplicate asset id: {asset_id}")
        path_value = _validate_asset_path_syntax(
            asset["path"], context=f"{context}.path"
        )
        if path_value in used_path_values:
            raise CliError(
                f"{context}.path duplicates another asset path: {path_value!r}"
            )
        used_path_values.add(path_value)
        role = require_string(asset["role"], context=f"{context}.role", maximum=16)
        if role not in {"figure", "logo", "qr_code"}:
            raise CliError(f"{context}.role must be figure, logo, or qr_code")
        digest = require_string(
            asset["sha256"], context=f"{context}.sha256", maximum=64
        )
        if not _SHA256.fullmatch(digest):
            raise CliError(f"{context}.sha256 must be 64 lowercase hex characters")
        source_id = _identifier(
            asset["source_id"], context=f"{context}.source_id"
        )
        used_sources.add(source_id)
        require_string(asset["license"], context=f"{context}.license", maximum=500)
        require_string(
            asset["provenance"],
            context=f"{context}.provenance",
            maximum=2_000,
        )
        require_string(
            asset["alt_text"], context=f"{context}.alt_text", maximum=1_000
        )
        if not require_bool(
            asset["author_approved"], context=f"{context}.author_approved"
        ):
            raise CliError(f"{context}.author_approved must be true")
        qr_target = asset["qr_target"]
        if role == "qr_code":
            target = require_string(
                qr_target, context=f"{context}.qr_target", maximum=2_000
            )
            authority = target[len("https://") :].split("/", 1)[0]
            if (
                not target.startswith("https://")
                or not authority
                or "@" in authority
                or any(character.isspace() for character in target)
            ):
                raise CliError(
                    f"{context}.qr_target must be an absolute https:// URL "
                    "without credentials or whitespace"
                )
        elif qr_target is not None:
            raise CliError(f"{context}.qr_target must be null for non-QR assets")
        if verify_assets:
            path = resolve_local_asset(
                manifest_path,
                path_value,
                suffixes=ASSET_SUFFIXES,
            )
            actual_digest = sha256_file(path)
            if actual_digest != digest:
                raise CliError(
                    f"{context}.sha256 mismatch for {path_value!r}: "
                    f"expected {digest}, got {actual_digest}"
                )
            paths[asset_id] = path
        assets[asset_id] = asset
    return assets, paths, used_sources


def _validate_box(
    item: dict[str, Any],
    *,
    context: str,
    canvas_width: float,
    canvas_height: float,
) -> tuple[float, float, float, float]:
    x = finite_number(item["x_in"], context=f"{context}.x_in", minimum=0.0)
    y = finite_number(item["y_in"], context=f"{context}.y_in", minimum=0.0)
    width = finite_number(
        item["width_in"], context=f"{context}.width_in", minimum=0.01
    )
    height = finite_number(
        item["height_in"], context=f"{context}.height_in", minimum=0.01
    )
    if x + width > canvas_width + 1e-6 or y + height > canvas_height + 1e-6:
        raise CliError(f"{context} extends beyond the PowerPoint canvas")
    return x, y, width, height


def _validate_elements(
    value: Any,
    *,
    document: dict[str, Any],
    canvas_width: float,
    canvas_height: float,
    print_scale: float,
    bleed: float,
    safe_margin: float,
    quality: dict[str, Any],
    colors: dict[str, str],
    contrast_pairs: dict[str, dict[str, Any]],
    assets: dict[str, dict[str, Any]],
) -> tuple[dict[str, dict[str, Any]], set[str], set[str]]:
    if not isinstance(value, list) or not 1 <= len(value) <= MAX_ELEMENTS:
        raise CliError(f"elements must contain between 1 and {MAX_ELEMENTS} objects")
    elements: dict[str, dict[str, Any]] = {}
    used_sources: set[str] = set()
    used_assets: set[str] = set()
    reading_orders: list[int] = []
    title_matches = 0
    safe_inset_design = (bleed + safe_margin) / print_scale

    common = {
        "id",
        "type",
        "reading_order",
        "x_in",
        "y_in",
        "width_in",
        "height_in",
        "source_ids",
        "author_approved",
        "allow_in_bleed",
    }
    text_keys = common | {
        "role",
        "text",
        "font_size_pt_design",
        "font_face",
        "bold",
        "align",
        "vertical_align",
        "contrast_pair_id",
        "line_color_id",
        "line_width_pt",
        "margin_in",
    }
    image_keys = common | {
        "asset_id",
        "fit",
        "fallback_text_element_id",
        "long_description_element_id",
    }

    for index, item in enumerate(value):
        context = f"elements[{index}]"
        if not isinstance(item, dict):
            raise CliError(f"{context} must be an object")
        element_type = require_string(
            item.get("type"), context=f"{context}.type", maximum=16
        )
        allowed = text_keys if element_type == "text" else image_keys
        if element_type not in {"text", "image"}:
            raise CliError(f"{context}.type must be text or image")
        element = reject_unknown_keys(
            item,
            context=context,
            allowed=allowed,
            required=allowed,
        )
        element_id = _identifier(element["id"], context=f"{context}.id")
        if element_id in elements:
            raise CliError(f"duplicate element id: {element_id}")
        order = positive_int(
            element["reading_order"],
            context=f"{context}.reading_order",
            maximum=MAX_ELEMENTS,
        )
        reading_orders.append(order)
        x, y, width, height = _validate_box(
            element,
            context=context,
            canvas_width=canvas_width,
            canvas_height=canvas_height,
        )
        source_ids = _source_id_list(
            element["source_ids"], context=f"{context}.source_ids"
        )
        used_sources.update(source_ids)
        if not require_bool(
            element["author_approved"], context=f"{context}.author_approved"
        ):
            raise CliError(f"{context}.author_approved must be true")
        allow_in_bleed = require_bool(
            element["allow_in_bleed"], context=f"{context}.allow_in_bleed"
        )
        if not allow_in_bleed:
            if (
                x < safe_inset_design - 1e-6
                or y < safe_inset_design - 1e-6
                or x + width > canvas_width - safe_inset_design + 1e-6
                or y + height > canvas_height - safe_inset_design + 1e-6
            ):
                raise CliError(
                    f"{context} crosses the confirmed final safe margin; "
                    "only intentional bleed imagery may set allow_in_bleed=true"
                )

        if element_type == "text":
            if allow_in_bleed:
                raise CliError(f"{context}: text must not be placed in the bleed area")
            role = require_string(
                element["role"], context=f"{context}.role", maximum=32
            )
            if role not in _TEXT_ROLES:
                raise CliError(
                    f"{context}.role must be one of {', '.join(sorted(_TEXT_ROLES))}"
                )
            text = require_string(
                element["text"], context=f"{context}.text", maximum=20_000
            )
            if role == "title" and text == document["title"]:
                title_matches += 1
            design_font = finite_number(
                element["font_size_pt_design"],
                context=f"{context}.font_size_pt_design",
                minimum=1.0,
                maximum=500.0,
            )
            final_font = design_font * print_scale
            minimum_font = float(quality["minimum_font_pt_final"])
            if final_font + 1e-6 < minimum_font:
                raise CliError(
                    f"{context} final font is {final_font:.2f} pt, below the "
                    f"manifest's {minimum_font:.2f} pt minimum"
                )
            require_string(
                element["font_face"], context=f"{context}.font_face", maximum=100
            )
            bold = require_bool(element["bold"], context=f"{context}.bold")
            align = require_string(
                element["align"], context=f"{context}.align", maximum=16
            )
            if align not in {"left", "center", "right"}:
                raise CliError(f"{context}.align must be left, center, or right")
            vertical = require_string(
                element["vertical_align"],
                context=f"{context}.vertical_align",
                maximum=16,
            )
            if vertical not in {"top", "middle", "bottom"}:
                raise CliError(
                    f"{context}.vertical_align must be top, middle, or bottom"
                )
            pair_id = _identifier(
                element["contrast_pair_id"],
                context=f"{context}.contrast_pair_id",
            )
            if pair_id not in contrast_pairs:
                raise CliError(f"{context} references unknown contrast pair {pair_id!r}")
            pair = contrast_pairs[pair_id]
            usage = pair["usage"]
            if usage == "non_text":
                raise CliError(f"{context} must use a text contrast pair")
            if usage == "large_text":
                is_large = final_font >= 18.0 or (bold and final_font >= 14.0)
                if not is_large:
                    raise CliError(
                        f"{context} uses a large_text contrast pair but is not "
                        "at least 18 pt final, or 14 pt final and bold"
                    )
            line_color_id = element["line_color_id"]
            if line_color_id is not None:
                line_id = _identifier(
                    line_color_id, context=f"{context}.line_color_id"
                )
                if line_id not in colors:
                    raise CliError(f"{context} references unknown line color {line_id!r}")
            line_width = finite_number(
                element["line_width_pt"],
                context=f"{context}.line_width_pt",
                minimum=0.0,
                maximum=72.0,
            )
            if line_color_id is None and line_width != 0:
                raise CliError(
                    f"{context}.line_width_pt must be 0 when line_color_id is null"
                )
            margin = finite_number(
                element["margin_in"],
                context=f"{context}.margin_in",
                minimum=0.0,
                maximum=5.0,
            )
            if 2 * margin >= min(width, height):
                raise CliError(f"{context}.margin_in consumes the text box")
        else:
            asset_id = _identifier(
                element["asset_id"], context=f"{context}.asset_id"
            )
            if asset_id not in assets:
                raise CliError(f"{context} references unknown asset {asset_id!r}")
            used_assets.add(asset_id)
            if assets[asset_id]["source_id"] not in source_ids:
                raise CliError(
                    f"{context}.source_ids must include the asset's exact source_id"
                )
            fit = require_string(element["fit"], context=f"{context}.fit", maximum=16)
            if fit != "contain":
                raise CliError(f"{context}.fit must be contain")
            fallback_id = element["fallback_text_element_id"]
            long_description_id = element["long_description_element_id"]
            if long_description_id is not None:
                _identifier(
                    long_description_id,
                    context=f"{context}.long_description_element_id",
                )
            if assets[asset_id]["role"] == "qr_code":
                _identifier(
                    fallback_id,
                    context=f"{context}.fallback_text_element_id",
                )
                if abs(width - height) > 1e-6:
                    raise CliError(f"{context}: QR placement box must be square")
                if long_description_id is not None:
                    raise CliError(
                        f"{context}.long_description_element_id must be null for "
                        "QR assets; use the required visible fallback text"
                    )
            elif fallback_id is not None:
                raise CliError(
                    f"{context}.fallback_text_element_id must be null for non-QR assets"
                )
        elements[element_id] = element

    expected_order = list(range(1, len(value) + 1))
    if sorted(reading_orders) != expected_order:
        raise CliError(
            "elements.reading_order values must be unique and contiguous from 1"
        )
    if reading_orders != expected_order:
        raise CliError(
            "elements must be listed in ascending reading_order so generation "
            "does not silently reorder approved content"
        )
    if title_matches != 1:
        raise CliError(
            "exactly one title element must match document.title verbatim"
        )
    title = next(
        element
        for element in elements.values()
        if element["type"] == "text"
        and element["role"] == "title"
        and element["text"] == document["title"]
    )
    if title["reading_order"] != 1:
        raise CliError(
            "the exact title element must have reading_order 1 so it can be the "
            "native PowerPoint slide title"
        )

    for element_id, element in elements.items():
        if element["type"] != "image":
            continue
        asset = assets[element["asset_id"]]
        long_description_id = element["long_description_element_id"]
        if long_description_id is not None:
            description = elements.get(long_description_id)
            if description is None or description["type"] != "text":
                raise CliError(
                    f"image {element_id!r} references missing text long description "
                    f"{long_description_id!r}"
                )
            if description["role"] not in {"body", "caption", "other"}:
                raise CliError(
                    f"long description {long_description_id!r} must have role "
                    "'body', 'caption', or 'other'"
                )
            if description["reading_order"] <= element["reading_order"]:
                raise CliError(
                    f"long description {long_description_id!r} must follow image "
                    f"{element_id!r} in reading order"
                )
            if not set(element["source_ids"]).issubset(description["source_ids"]):
                raise CliError(
                    f"long description {long_description_id!r} must include every "
                    f"source_id used by image {element_id!r}"
                )
        if asset["role"] != "qr_code":
            continue
        fallback_id = element["fallback_text_element_id"]
        fallback = elements.get(fallback_id)
        if fallback is None or fallback["type"] != "text":
            raise CliError(
                f"QR image {element_id!r} references missing text fallback "
                f"{fallback_id!r}"
            )
        if fallback["role"] != "qr_fallback":
            raise CliError(
                f"QR fallback {fallback_id!r} must have role 'qr_fallback'"
            )
        if asset["qr_target"] not in fallback["text"]:
            raise CliError(
                f"QR fallback {fallback_id!r} must contain the exact QR target URL"
            )
    return elements, used_sources, used_assets


def _validate_approval(
    value: Any,
    *,
    content_hash: str,
    require_approval: bool,
) -> dict[str, Any]:
    approval = reject_unknown_keys(
        value,
        context="approval",
        allowed={"status", "approved_by", "approved_at", "content_sha256"},
        required={"status", "approved_by", "approved_at", "content_sha256"},
    )
    status = require_string(approval["status"], context="approval.status", maximum=16)
    if status not in {"draft", "approved"}:
        raise CliError("approval.status must be draft or approved")
    if require_approval and status != "approved":
        raise CliError("approval.status must be approved")
    if status == "approved":
        require_string(
            approval["approved_by"],
            context="approval.approved_by",
            maximum=200,
        )
        parse_aware_datetime(approval["approved_at"], context="approval.approved_at")
        digest = require_string(
            approval["content_sha256"],
            context="approval.content_sha256",
            maximum=64,
        )
        if not _SHA256.fullmatch(digest):
            raise CliError(
                "approval.content_sha256 must be 64 lowercase hex characters"
            )
        if digest != content_hash:
            raise CliError(
                "approval.content_sha256 does not match the current manifest content; "
                "author approval must be renewed after every content change"
            )
    else:
        for key in ("approved_by", "approved_at", "content_sha256"):
            if approval[key] is not None:
                raise CliError(f"approval.{key} must be null while status is draft")
    return approval


def validate_manifest_document(
    document: Any,
    *,
    manifest_path: Path,
    verify_assets: bool = True,
    require_approval: bool = True,
    enforce_contrast: bool = True,
) -> dict[str, Any]:
    """Validate a parsed manifest and return a non-content audit report."""
    manifest = reject_unknown_keys(
        document,
        context="manifest",
        allowed=_TOP_KEYS,
        required=_TOP_KEYS,
    )
    if manifest["schema_version"] != MANIFEST_SCHEMA_VERSION:
        raise CliError(
            f"schema_version must be {MANIFEST_SCHEMA_VERSION!r}, got "
            f"{manifest['schema_version']!r}"
        )
    placeholder = has_placeholder(manifest)
    if placeholder is not None:
        path, text = placeholder
        raise CliError(f"placeholder content is forbidden at {path}: {text!r}")

    document_record = _validate_document(manifest["document"])
    _, canvas_width, canvas_height = _validate_canvas(manifest["canvas"])
    (
        _,
        trim_width,
        trim_height,
        bleed,
        safe_margin,
        artboard_width,
        artboard_height,
    ) = _validate_physical_output(manifest["physical_output"])
    scale_x = artboard_width / canvas_width
    scale_y = artboard_height / canvas_height
    if abs(scale_x - scale_y) > max(1e-6, scale_x * 0.001):
        raise CliError(
            "PowerPoint canvas and final artboard have different aspect ratios; "
            "nonuniform print scaling is forbidden"
        )
    print_scale = (scale_x + scale_y) / 2.0

    sources = _validate_sources(manifest["sources"])
    requirements, requirement_sources = _validate_requirements(
        manifest["requirements"],
        trim_width=trim_width,
        trim_height=trim_height,
        bleed=bleed,
        safe_margin=safe_margin,
        print_scale=print_scale,
    )
    quality, quality_sources = _validate_quality(manifest["quality"])
    _, colors, contrast_pairs = _validate_palette(
        manifest["palette"],
        enforce_thresholds=enforce_contrast,
    )
    assets, asset_paths, asset_sources = _validate_assets(
        manifest["assets"],
        manifest_path=manifest_path,
        verify_assets=verify_assets,
    )
    elements, element_sources, used_assets = _validate_elements(
        manifest["elements"],
        document=document_record,
        canvas_width=canvas_width,
        canvas_height=canvas_height,
        print_scale=print_scale,
        bleed=bleed,
        safe_margin=safe_margin,
        quality=quality,
        colors=colors,
        contrast_pairs=contrast_pairs,
        assets=assets,
    )
    if set(assets) != used_assets:
        unused = sorted(set(assets) - used_assets)
        raise CliError(f"unused assets are forbidden: {', '.join(unused)}")

    used_sources = (
        requirement_sources
        | quality_sources
        | asset_sources
        | element_sources
        | set(document_record["source_ids"])
    )
    unknown_sources = sorted(used_sources - set(sources))
    if unknown_sources:
        raise CliError(
            f"unknown exact source id(s): {', '.join(unknown_sources)}"
        )
    expected_source_kinds = {
        requirements["conference"]["source_id"]: "conference_rule",
        requirements["printer"]["source_id"]: "printer_rule",
    }
    for source_id, expected_kind in expected_source_kinds.items():
        if sources[source_id]["kind"] != expected_kind:
            raise CliError(
                f"source {source_id!r} must have kind {expected_kind!r} for its "
                "declared requirement"
            )
    for prefix, expected_kind in (
        ("font_guidance", "conference_rule"),
        ("raster_dpi", "conference_rule"),
    ):
        basis = quality[f"{prefix}_basis"]
        source_id = quality[f"{prefix}_source_id"]
        if basis == "conference_requirement" and sources[source_id]["kind"] != expected_kind:
            raise CliError(
                f"quality.{prefix}_source_id must reference a conference_rule"
            )
        if (
            basis == "printer_requirement"
            and sources[source_id]["kind"] != "printer_rule"
        ):
            raise CliError(
                f"quality.{prefix}_source_id must reference a printer_rule"
            )
    unused_sources = sorted(set(sources) - used_sources)
    if unused_sources:
        raise CliError(f"unused source records are forbidden: {', '.join(unused_sources)}")

    content_hash = manifest_content_hash(manifest)
    approval = _validate_approval(
        manifest["approval"],
        content_hash=content_hash,
        require_approval=require_approval,
    )
    return {
        "schema_version": REPORT_SCHEMA_VERSION,
        "valid": True,
        "manifest_path": str(manifest_path),
        "manifest_schema_version": MANIFEST_SCHEMA_VERSION,
        "content_sha256": content_hash,
        "approval_status": approval["status"],
        "assets_verified": verify_assets,
        "asset_paths": {key: str(value) for key, value in asset_paths.items()},
        "counts": {
            "sources": len(sources),
            "assets": len(assets),
            "elements": len(elements),
            "text_elements": sum(
                element["type"] == "text" for element in elements.values()
            ),
            "image_elements": sum(
                element["type"] == "image" for element in elements.values()
            ),
        },
        "canvas": {
            "width_in": canvas_width,
            "height_in": canvas_height,
        },
        "physical_output": {
            "trim_width_in": trim_width,
            "trim_height_in": trim_height,
            "bleed_in": bleed,
            "safe_margin_in": safe_margin,
            "artboard_width_in": artboard_width,
            "artboard_height_in": artboard_height,
            "print_scale": print_scale,
            "print_scale_percent": print_scale * 100.0,
        },
        "quality_basis": {
            "minimum_font_pt_final": float(quality["minimum_font_pt_final"]),
            "font_guidance_basis": quality["font_guidance_basis"],
            "minimum_raster_dpi_final": float(
                quality["minimum_raster_dpi_final"]
            ),
            "raster_dpi_basis": quality["raster_dpi_basis"],
        },
        "delivery": {
            "conference_format": requirements["conference"][
                "required_delivery_format"
            ],
            "printer_color_mode": requirements["printer"][
                "accepted_color_mode"
            ],
            "printer_scaling_allowed": requirements["printer"]["scaling_allowed"],
        },
    }


def load_and_validate_manifest(
    value: str | Path,
    *,
    verify_assets: bool = True,
    require_approval: bool = True,
    enforce_contrast: bool = True,
) -> tuple[Path, dict[str, Any], dict[str, Any]]:
    """Load strict JSON and validate the complete poster manifest."""
    path, document = load_json_file(value)
    report = validate_manifest_document(
        document,
        manifest_path=path,
        verify_assets=verify_assets,
        require_approval=require_approval,
        enforce_contrast=enforce_contrast,
    )
    return path, document, report