"""Document ingest — raw text / bytes → UTF-8 string."""

from __future__ import annotations


def ingest_text(source: str | bytes | None, *, encoding: str = "utf-8") -> str:
    """Normalize input into a UTF-8 Unicode string."""
    if source is None:
        return ""
    if isinstance(source, bytes):
        for enc in (encoding, "utf-8", "utf-8-sig", "latin-1"):
            try:
                return source.decode(enc)
            except (UnicodeDecodeError, LookupError):
                continue
        return source.decode("utf-8", errors="replace")
    return str(source)