"""
Shared extractor contract.

Every extractor exposes `extract(source: Path, options: dict) -> ExtractionResult`
and is isolated: a failure on one file is caught by the workflow and recorded,
never aborting a batch (same resilience as ctrl/batch.sh).
"""
from dataclasses import dataclass, field
from typing import Optional, List, Dict, Any


@dataclass
class ExtractionResult:
    """What an extractor returns.

    content   textified document as markdown/plain text — the shareable product.
    metadata  type-specific fields (title, author, created/modified, pages,
              sheet/slide names, structure summary, ...). Merged into meta.json.
    thumb     optional JPEG bytes for thumb.jpg (page 1 / slide 1 / the image).
    warnings  non-fatal issues to surface in meta.json.
    extractor id string, e.g. "office/python-docx@1".
    """

    content: str = ""
    metadata: Dict[str, Any] = field(default_factory=dict)
    thumb: Optional[bytes] = None
    warnings: List[str] = field(default_factory=list)
    extractor: str = ""