ummaya 0.2.4 → 0.2.6

package/src/ummaya/evidence/document_harness.py

@@ -0,0 +1,313 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Document harness evidence records for Evidence Fabric v2.
+
+This module stores only join metadata for document reports. Document bytes,
+extracted text, and filled field values stay in the local artifact/report store
+and are referenced here by opaque IDs plus SHA-256 hashes.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Literal
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, model_validator
+
+from ummaya.evidence.document_authoring_cases import DocumentAuthoringCase
+from ummaya.evidence.json_types import JsonObject, parse_json_object
+from ummaya.evidence.models import RunEvidence
+from ummaya.tools.documents.models import DocumentFormatFamily, KnownDocumentFormat
+
+_REPO_ROOT = Path(__file__).resolve().parents[3]
+_DEFAULT_DOCUMENT_SCENARIO_PATH = _REPO_ROOT / "evidence/scenarios/document_harness_v1.yaml"
+
+DocumentHarnessReadiness = Literal[
+    "ready_for_review",
+    "not_ready",
+    "blocked",
+    "unsupported",
+]
+DocumentHarnessFormat = Literal["hwpx", "docx", "xlsx", "pdf", "pptx"]
+DocumentHarnessLifecycleStage = Literal[
+    "intake",
+    "classification",
+    "capability",
+    "adapter_selection",
+    "permission",
+    "mutation",
+    "render",
+    "reread",
+    "validation",
+    "diff",
+    "tui_frame",
+]
+DocumentHarnessLifecycleStatus = Literal[
+    "pass",
+    "blocked",
+    "needs_input",
+    "unsupported",
+    "ready_for_review",
+]
+DocumentHarnessBetaDomain = Literal[
+    "weekly_log",
+    "contest_proposal",
+    "consent",
+    "pledge",
+    "spreadsheet",
+    "pdf_form",
+    "presentation",
+    "public_data_csv_json",
+    "static_pdf",
+    "scanned_image",
+    "archive_bundle",
+]
+DocumentHarnessBetaOutcome = Literal[
+    "ready_for_review",
+    "read_only",
+    "blocked",
+    "needs_input",
+    "unsupported",
+]
+DocumentHarnessNegativeTrigger = Literal[
+    "missing_file",
+    "ambiguous_file_candidates",
+    "unsupported_known_format",
+    "blocked_hwp_write",
+    "static_pdf_fill",
+    "macro_active_content",
+    "path_traversal",
+    "oversized_archive",
+    "external_link",
+]
+
+
+class DocumentHarnessEvidenceError(ValueError):
+    """Raised when document harness evidence metadata is invalid."""
+
+
+class DocumentEvidenceRecord(BaseModel):
+    """Joinable evidence record for one generated document derivative."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    record_id: str
+    scenario_id: str
+    correlation_id: str
+    source_artifact_id: str
+    source_sha256: str = Field(pattern=r"^[0-9a-f]{64}$")
+    derivative_artifact_id: str
+    derivative_sha256: str = Field(pattern=r"^[0-9a-f]{64}$")
+    structured_diff_id: str
+    structured_diff_sha256: str = Field(pattern=r"^[0-9a-f]{64}$")
+    render_artifact_ids: tuple[str, ...] = Field(min_length=1)
+    validation_report_id: str
+    validation_report_sha256: str = Field(pattern=r"^[0-9a-f]{64}$")
+    readiness: DocumentHarnessReadiness
+
+
+class DocumentHarnessEvidenceEnvelope(BaseModel):
+    """Evidence Fabric runner output plus document-specific evidence records."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid", strict=True)
+
+    run_evidence: RunEvidence
+    document_evidence_records: tuple[DocumentEvidenceRecord, ...]
+
+
+class DocumentLifecycleEvidenceRecord(BaseModel):
+    """Join-only evidence for one document workflow stage."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    record_id: str
+    scenario_id: str
+    correlation_id: str
+    stage: DocumentHarnessLifecycleStage
+    status: DocumentHarnessLifecycleStatus
+    known_format: KnownDocumentFormat
+    format_family: DocumentFormatFamily
+    support_component_id: str | None = None
+    artifact_id: str | None = None
+    artifact_sha256: str | None = Field(default=None, pattern=r"^[0-9a-f]{64}$")
+    document_diff_id: str | None = None
+    frame_hash: str | None = Field(default=None, pattern=r"^sha256:[0-9a-f]{64}$")
+    evidence_ref: str
+
+    @model_validator(mode="after")
+    def _tui_frame_requires_frame_hash(self) -> DocumentLifecycleEvidenceRecord:
+        if self.stage == "tui_frame" and self.frame_hash is None:
+            raise ValueError("tui_frame lifecycle evidence requires frame_hash")
+        return self
+
+
+class DocumentBetaCase(BaseModel):
+    """Representative beta scenario for one Public AX document domain."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    case_id: str
+    domain: DocumentHarnessBetaDomain
+    known_format: KnownDocumentFormat
+    format_family: DocumentFormatFamily
+    expected_outcome: DocumentHarnessBetaOutcome
+    expected_operation: str
+    fixture_id: str | None = None
+    evidence_ref: str
+
+
+class DocumentNegativeCase(BaseModel):
+    """Negative beta scenario that must fail closed."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    case_id: str
+    trigger: DocumentHarnessNegativeTrigger
+    expected_status: Literal["blocked", "needs_input"]
+    expected_reason: str
+    derivative_save: Literal["forbidden"]
+    evidence_ref: str
+
+
+class DocumentHarnessAcceptanceGates(BaseModel):
+    """US4 acceptance gates for the document harness scenario."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    original_mutation: Literal["blocked"]
+    derivative_lineage: Literal["required"]
+    structured_result_schema: Literal["required"]
+    render_reread_evidence: Literal["required"]
+    live_government_calls: Literal["forbidden"]
+
+
+class DocumentHarnessFixture(BaseModel):
+    """Offline fixture metadata used to prove document evidence joins."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    fixture_id: str
+    format: DocumentHarnessFormat
+    source_artifact_id: str
+    source_sha256: str = Field(pattern=r"^[0-9a-f]{64}$")
+    derivative_artifact_id: str
+    derivative_sha256: str = Field(pattern=r"^[0-9a-f]{64}$")
+    structured_diff_id: str
+    structured_diff_sha256: str = Field(pattern=r"^[0-9a-f]{64}$")
+    render_artifact_ids: tuple[str, ...] = Field(min_length=1)
+    validation_report_id: str
+    validation_report_sha256: str = Field(pattern=r"^[0-9a-f]{64}$")
+    expected_correlation_id: str
+
+
+class DocumentHarnessScenario(BaseModel):
+    """Dedicated US4 scenario metadata for document harness evidence."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    version: int
+    scenario_id: Literal["document_harness_v1"]
+    created_at: str
+    source_basis: Literal["document_production_hardening_spec"]
+    target_system: str
+    network_policy: Literal["offline_only"]
+    required_sequence: tuple[Literal["document"], ...]
+    acceptance_gates: DocumentHarnessAcceptanceGates
+    fixtures: tuple[DocumentHarnessFixture, ...] = Field(min_length=1)
+    lifecycle_records: tuple[DocumentLifecycleEvidenceRecord, ...] = Field(min_length=1)
+    beta_cases: tuple[DocumentBetaCase, ...] = Field(min_length=1)
+    negative_cases: tuple[DocumentNegativeCase, ...] = Field(min_length=1)
+    authoring_cases: tuple[DocumentAuthoringCase, ...] = Field(min_length=1)
+
+
+def load_document_harness_scenario(
+    path: Path = _DEFAULT_DOCUMENT_SCENARIO_PATH,
+) -> DocumentHarnessScenario:
+    """Load the offline document harness Evidence Fabric scenario."""
+
+    raw = _load_yaml_mapping(path)
+    try:
+        return DocumentHarnessScenario.model_validate(raw)
+    except ValidationError as exc:
+        raise DocumentHarnessEvidenceError(str(exc)) from exc
+
+
+def attach_document_evidence_records(
+    run_evidence: RunEvidence,
+    records: Sequence[DocumentEvidenceRecord],
+) -> DocumentHarnessEvidenceEnvelope:
+    """Attach document records to an Evidence Fabric runner result."""
+
+    return DocumentHarnessEvidenceEnvelope(
+        run_evidence=run_evidence,
+        document_evidence_records=tuple(records),
+    )
+
+
+def records_from_scenario(
+    scenario: DocumentHarnessScenario,
+) -> tuple[DocumentEvidenceRecord, ...]:
+    """Build join-only document evidence records from scenario fixture metadata."""
+
+    return tuple(
+        DocumentEvidenceRecord(
+            record_id=f"doc-evidence-{fixture.fixture_id}",
+            scenario_id=scenario.scenario_id,
+            correlation_id=fixture.expected_correlation_id,
+            source_artifact_id=fixture.source_artifact_id,
+            source_sha256=fixture.source_sha256,
+            derivative_artifact_id=fixture.derivative_artifact_id,
+            derivative_sha256=fixture.derivative_sha256,
+            structured_diff_id=fixture.structured_diff_id,
+            structured_diff_sha256=fixture.structured_diff_sha256,
+            render_artifact_ids=fixture.render_artifact_ids,
+            validation_report_id=fixture.validation_report_id,
+            validation_report_sha256=fixture.validation_report_sha256,
+            readiness="ready_for_review",
+        )
+        for fixture in scenario.fixtures
+    )
+
+
+def lifecycle_records_from_scenario(
+    scenario: DocumentHarnessScenario,
+) -> tuple[DocumentLifecycleEvidenceRecord, ...]:
+    """Return workflow lifecycle records from scenario metadata."""
+
+    return scenario.lifecycle_records
+
+
+def beta_cases_from_scenario(
+    scenario: DocumentHarnessScenario,
+) -> tuple[DocumentBetaCase, ...]:
+    """Return beta-matrix cases from scenario metadata."""
+
+    return scenario.beta_cases
+
+
+def negative_cases_from_scenario(
+    scenario: DocumentHarnessScenario,
+) -> tuple[DocumentNegativeCase, ...]:
+    """Return fail-closed beta-matrix cases from scenario metadata."""
+
+    return scenario.negative_cases
+
+
+def authoring_cases_from_scenario(
+    scenario: DocumentHarnessScenario,
+) -> tuple[DocumentAuthoringCase, ...]:
+    return scenario.authoring_cases
+
+
+def _load_yaml_mapping(path: Path) -> JsonObject:
+    resolved = path if path.is_absolute() else _REPO_ROOT / path
+    if not resolved.exists():
+        raise DocumentHarnessEvidenceError(f"document harness scenario not found: {path}")
+    loaded = yaml.safe_load(resolved.read_text(encoding="utf-8"))
+    try:
+        return parse_json_object(loaded)
+    except ValidationError as exc:
+        raise DocumentHarnessEvidenceError(
+            f"document harness scenario must be a JSON mapping: {path}"
+        ) from exc

package/src/ummaya/evidence/document_viewer_ux.py

@@ -0,0 +1,391 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Playwright-captured UX evidence for local document viewers."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import subprocess
+import zlib
+from collections.abc import Iterator, Mapping
+from contextlib import contextmanager
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from functools import partial
+from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from threading import Thread
+from typing import Literal, Protocol, cast
+from urllib.parse import quote
+from uuid import uuid4
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+
+class DocumentViewerUxEvidenceError(ValueError):
+    """Raised when document viewer UX evidence cannot be captured."""
+
+
+class DocumentViewerViewportRect(BaseModel):
+    """Viewport rectangle from a hidden document viewer manifest."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    x: float
+    y: float
+    width: float
+    height: float
+
+
+class DocumentViewerManifest(BaseModel):
+    """Subset of viewer-manifest.json needed for Evidence Fabric joins."""
+
+    model_config = ConfigDict(frozen=True, extra="allow")
+
+    viewer_artifact_id: str
+    mode: Literal["compact", "expand"]
+    page_index: int = 0
+    correlation_id: str | None = None
+    document_diff_id: str | None = None
+    source_render_artifact_id: str
+    baseline_render_artifact_id: str | None = None
+    viewport_rect: DocumentViewerViewportRect | None = None
+    change_ids: tuple[str, ...] = Field(default_factory=tuple)
+    local_only: bool = True
+
+
+class DocumentViewerUxArtifact(BaseModel):
+    """Join-only UX artifact record for a Playwright document viewer screenshot."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid", strict=True)
+
+    artifact_kind: Literal["document_viewer_png"] = "document_viewer_png"
+    artifact_id: str
+    source_ref: str
+    capture_tool: Literal["playwright"] = "playwright"
+    captured_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    viewer_artifact_id: str
+    mode: Literal["compact", "expand"]
+    correlation_id: str
+    document_diff_id: str | None = None
+    viewer_html_path: str
+    viewer_manifest_path: str
+    screenshot_path: str
+    screenshot_sha256: str = Field(pattern=r"^[0-9a-f]{64}$")
+    frame_hash: str = Field(pattern=r"^sha256:[0-9a-f]{64}$")
+    page_index: int
+    source_render_artifact_id: str
+    baseline_render_artifact_id: str | None = None
+    viewport_rect: DocumentViewerViewportRect | None = None
+    change_ids: tuple[str, ...] = Field(default_factory=tuple)
+    local_only: bool
+
+
+class PlaywrightCapture(Protocol):
+    """Callable boundary for Playwright screenshot capture."""
+
+    def __call__(self, *, viewer_url: str, output_path: Path) -> None:
+        """Capture ``viewer_url`` into ``output_path`` as a PNG."""
+
+
+@dataclass(frozen=True)
+class _PngImageData:
+    width: int
+    height: int
+    color_type: int
+    compressed_data: bytes
+
+
+def capture_document_viewer_ux_artifact(
+    *,
+    viewer_html_path: Path,
+    output_dir: Path,
+    source_ref: str,
+    correlation_id: str | None = None,
+    document_diff_id: str | None = None,
+    capture: PlaywrightCapture | None = None,
+) -> DocumentViewerUxArtifact:
+    """Capture a local document viewer with Playwright and return join metadata."""
+
+    viewer_html = viewer_html_path.resolve()
+    if not viewer_html.exists():
+        raise DocumentViewerUxEvidenceError(f"document viewer html not found: {viewer_html}")
+    manifest_path = viewer_html.parent / "viewer-manifest.json"
+    manifest = _load_manifest(manifest_path)
+    resolved_correlation_id = correlation_id or manifest.correlation_id
+    if resolved_correlation_id is None or resolved_correlation_id.strip() == "":
+        raise DocumentViewerUxEvidenceError(
+            "document viewer UX evidence requires a correlation_id in the "
+            "viewer manifest or CLI argument"
+        )
+    resolved_diff_id = document_diff_id or manifest.document_diff_id
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+    screenshot_path = (
+        output_dir / f"{manifest.viewer_artifact_id}-{manifest.mode}-playwright.png"
+    ).resolve()
+    capture_impl = capture or capture_with_playwright_cli
+    with _serve_viewer_directory(viewer_html) as viewer_url:
+        capture_impl(viewer_url=viewer_url, output_path=screenshot_path)
+    if not screenshot_path.exists():
+        raise DocumentViewerUxEvidenceError(
+            f"Playwright did not create screenshot: {screenshot_path}"
+        )
+    if not _png_has_visible_nonwhite_pixel(screenshot_path):
+        raise DocumentViewerUxEvidenceError(
+            f"Playwright document viewer capture is blank: {screenshot_path}"
+        )
+    screenshot_sha256 = _sha256_file(screenshot_path)
+
+    return DocumentViewerUxArtifact(
+        artifact_id=f"ux-{manifest.viewer_artifact_id}-{screenshot_sha256[:12]}",
+        source_ref=source_ref,
+        viewer_artifact_id=manifest.viewer_artifact_id,
+        mode=manifest.mode,
+        correlation_id=resolved_correlation_id,
+        document_diff_id=resolved_diff_id,
+        viewer_html_path=str(viewer_html),
+        viewer_manifest_path=str(manifest_path.resolve()),
+        screenshot_path=str(screenshot_path),
+        screenshot_sha256=screenshot_sha256,
+        frame_hash=f"sha256:{screenshot_sha256}",
+        page_index=manifest.page_index,
+        source_render_artifact_id=manifest.source_render_artifact_id,
+        baseline_render_artifact_id=manifest.baseline_render_artifact_id,
+        viewport_rect=manifest.viewport_rect,
+        change_ids=manifest.change_ids,
+        local_only=manifest.local_only,
+    )
+
+
+def capture_with_playwright_cli(*, viewer_url: str, output_path: Path) -> None:
+    """Capture a viewer URL through the bundled Playwright CLI wrapper."""
+
+    wrapper = Path(os.environ.get("CODEX_HOME", str(Path.home() / ".codex"))) / (
+        "skills/playwright/scripts/playwright_cli.sh"
+    )
+    if not wrapper.exists():
+        raise DocumentViewerUxEvidenceError(f"Playwright CLI wrapper not found: {wrapper}")
+    session = f"udv-{uuid4().hex[:12]}"
+    env = os.environ.copy()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    commands = (
+        (str(wrapper), f"-s={session}", "open", viewer_url),
+        (str(wrapper), f"-s={session}", "resize", "1600", "1000"),
+        (
+            str(wrapper),
+            f"-s={session}",
+            "eval",
+            "() => document.documentElement.dataset.ready || document.readyState",
+        ),
+        (
+            str(wrapper),
+            f"-s={session}",
+            "screenshot",
+            "--filename",
+            str(output_path),
+            "--full-page",
+        ),
+    )
+    try:
+        for command in commands:
+            subprocess.run(  # noqa: S603 - fixed local Playwright wrapper plus typed args.
+                command,
+                check=True,
+                capture_output=True,
+                text=True,
+                env=env,
+            )
+    except subprocess.CalledProcessError as exc:
+        detail = (exc.stderr or exc.stdout or str(exc)).strip()
+        raise DocumentViewerUxEvidenceError(
+            f"Playwright document viewer capture failed: {detail}"
+        ) from exc
+    finally:
+        subprocess.run(  # noqa: S603 - cleanup uses the same fixed local wrapper.
+            (str(wrapper), f"-s={session}", "close"),
+            check=False,
+            capture_output=True,
+            text=True,
+            env=env,
+        )
+
+
+def _load_manifest(path: Path) -> DocumentViewerManifest:
+    if not path.exists():
+        raise DocumentViewerUxEvidenceError(f"viewer manifest not found: {path}")
+    loaded = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(loaded, Mapping):
+        raise DocumentViewerUxEvidenceError(f"viewer manifest must be a mapping: {path}")
+    try:
+        return DocumentViewerManifest.model_validate(cast(Mapping[str, object], loaded))
+    except ValidationError as exc:
+        raise DocumentViewerUxEvidenceError(str(exc)) from exc
+
+
+@contextmanager
+def _serve_viewer_directory(viewer_html: Path) -> Iterator[str]:
+    handler = partial(
+        _QuietViewerRequestHandler,
+        directory=str(viewer_html.parent),
+    )
+    server = ThreadingHTTPServer(("127.0.0.1", 0), handler)
+    thread = Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    try:
+        port = int(server.server_address[1])
+        yield f"http://127.0.0.1:{port}/{quote(viewer_html.name)}"
+    finally:
+        server.shutdown()
+        server.server_close()
+        thread.join(timeout=2)
+
+
+class _QuietViewerRequestHandler(SimpleHTTPRequestHandler):
+    def log_message(self, message_format: str, *args: object) -> None:
+        del message_format, args
+
+
+def _png_has_visible_nonwhite_pixel(path: Path) -> bool:
+    image = _load_png_image_data(path)
+    channels = 4 if image.color_type == 6 else 3
+    stride = image.width * channels
+    raw = zlib.decompress(image.compressed_data)
+    previous = bytearray(stride)
+    offset = 0
+    for _row in range(image.height):
+        filter_type, scanline, offset = _read_png_scanline(
+            raw,
+            offset,
+            stride,
+            path,
+        )
+        _unfilter_png_scanline(scanline, previous, channels, filter_type)
+        if _scanline_has_visible_nonwhite_pixel(scanline, channels):
+            return True
+        previous = scanline
+    return False
+
+
+def _load_png_image_data(path: Path) -> _PngImageData:
+    data = path.read_bytes()
+    if not data.startswith(b"\x89PNG\r\n\x1a\n"):
+        raise DocumentViewerUxEvidenceError(f"Playwright screenshot is not a PNG: {path}")
+    width = 0
+    height = 0
+    bit_depth = 0
+    color_type = 0
+    interlace = 0
+    idat_chunks: list[bytes] = []
+    for chunk_type, chunk_data in _iter_png_chunks(data, path):
+        if chunk_type == b"IHDR":
+            width = int.from_bytes(chunk_data[0:4], "big")
+            height = int.from_bytes(chunk_data[4:8], "big")
+            bit_depth = chunk_data[8]
+            color_type = chunk_data[9]
+            interlace = chunk_data[12]
+        elif chunk_type == b"IDAT":
+            idat_chunks.append(chunk_data)
+        elif chunk_type == b"IEND":
+            break
+    if width <= 0 or height <= 0 or not idat_chunks:
+        raise DocumentViewerUxEvidenceError(f"invalid PNG screenshot: {path}")
+    if bit_depth != 8 or color_type not in (2, 6) or interlace != 0:
+        raise DocumentViewerUxEvidenceError(
+            f"unsupported PNG screenshot format: bit_depth={bit_depth} "
+            f"color_type={color_type} interlace={interlace}"
+        )
+    return _PngImageData(
+        width=width,
+        height=height,
+        color_type=color_type,
+        compressed_data=b"".join(idat_chunks),
+    )
+
+
+def _iter_png_chunks(data: bytes, path: Path) -> Iterator[tuple[bytes, bytes]]:
+    pos = 8
+    while pos + 8 <= len(data):
+        chunk_len = int.from_bytes(data[pos : pos + 4], "big")
+        chunk_type = data[pos + 4 : pos + 8]
+        chunk_start = pos + 8
+        chunk_end = chunk_start + chunk_len
+        if chunk_end + 4 > len(data):
+            raise DocumentViewerUxEvidenceError(f"invalid PNG chunk bounds: {path}")
+        yield chunk_type, data[chunk_start:chunk_end]
+        pos = chunk_end + 4
+        if chunk_type == b"IEND":
+            break
+
+
+def _read_png_scanline(
+    raw: bytes,
+    offset: int,
+    stride: int,
+    path: Path,
+) -> tuple[int, bytearray, int]:
+    if offset >= len(raw):
+        raise DocumentViewerUxEvidenceError(f"truncated PNG scanline data: {path}")
+    filter_type = raw[offset]
+    next_offset = offset + 1
+    scanline = bytearray(raw[next_offset : next_offset + stride])
+    if len(scanline) != stride:
+        raise DocumentViewerUxEvidenceError(f"truncated PNG scanline data: {path}")
+    return filter_type, scanline, next_offset + stride
+
+
+def _scanline_has_visible_nonwhite_pixel(scanline: bytearray, channels: int) -> bool:
+    for pixel in range(0, len(scanline), channels):
+        red = scanline[pixel]
+        green = scanline[pixel + 1]
+        blue = scanline[pixel + 2]
+        alpha = scanline[pixel + 3] if channels == 4 else 255
+        if alpha > 0 and (red < 250 or green < 250 or blue < 250):
+            return True
+    return False
+
+
+def _unfilter_png_scanline(
+    scanline: bytearray,
+    previous: bytearray,
+    bytes_per_pixel: int,
+    filter_type: int,
+) -> None:
+    for index, value in enumerate(scanline):
+        left = scanline[index - bytes_per_pixel] if index >= bytes_per_pixel else 0
+        up = previous[index]
+        up_left = previous[index - bytes_per_pixel] if index >= bytes_per_pixel else 0
+        if filter_type == 0:
+            restored = value
+        elif filter_type == 1:
+            restored = value + left
+        elif filter_type == 2:
+            restored = value + up
+        elif filter_type == 3:
+            restored = value + ((left + up) // 2)
+        elif filter_type == 4:
+            restored = value + _paeth_predictor(left, up, up_left)
+        else:
+            raise DocumentViewerUxEvidenceError(f"unsupported PNG filter type: {filter_type}")
+        scanline[index] = restored & 0xFF
+
+
+def _paeth_predictor(left: int, up: int, up_left: int) -> int:
+    estimate = left + up - up_left
+    distance_left = abs(estimate - left)
+    distance_up = abs(estimate - up)
+    distance_up_left = abs(estimate - up_left)
+    if distance_left <= distance_up and distance_left <= distance_up_left:
+        return left
+    if distance_up <= distance_up_left:
+        return up
+    return up_left
+
+
+def _sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as file:
+        for chunk in iter(lambda: file.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()