from pathlib import Path
from collections.abc import Sequence

def resolve_pdf_files(
    folder: Path,
    files: Sequence[Path | str] | None = None,
    max_files: int | None = None,
) -> list[Path]:
    return resolve_files(folder, "pdf", files, max_files)

def resolve_files(
    folder: Path,
    suffix: str = "pdf",
    files: Sequence[Path | str] | None = None,
    max_files: int | None = None,
) -> list[Path]:
    """Resolve and normalize PDF file paths for ingestion handlers."""
    search_root = folder
    candidate_files: list[Path]
    if files:
        candidate_files = [Path(file).expanduser() for file in files]
    else:
        candidate_files = sorted(search_root.rglob(f"*.{suffix}"))

    resolved_files: list[Path] = []
    for file in candidate_files:
        if file.is_absolute():
            resolved = file
        elif file.exists():
            resolved = file.resolve()
        else:
            resolved = (search_root / file).resolve()
        if resolved.exists() and resolved.is_file() and resolved.suffix.lower() == ".pdf":
            resolved_files.append(resolved)

    resolved_files = sorted(set(resolved_files), key=lambda path: str(path))
    if max_files is not None:
        resolved_files = resolved_files[:max_files]
    return resolved_files