"""Provenance envelope shared across adapters and warehouse."""

from dataclasses import dataclass
from typing import Any


@dataclass(frozen=True)
class Envelope:
    """Provenance wrapper for a raw source response.

    Adapters produce Envelopes.  The raw warehouse persists them.

    Fields:
        source:     Identifier for the source system (e.g. "fitbit", "fddb").
        endpoint:   The API path or page that produced this payload.
        fetched_at: ISO 8601 timestamp of when the pipeline observed the data.
        payload:    The raw response — dict for JSON APIs, str for HTML.
    """

    source: str
    endpoint: str
    fetched_at: str
    payload: Any
