"""Payload model for the telegram_backfill_job_ready Kafka topic.

Published by sam-backend's gap scanner and consumed by tele-crawler's
backfill worker.  Each message represents one chunk of a detected gap
that the worker should fetch via Telethon.
"""

from __future__ import annotations

from pydantic import BaseModel, ConfigDict


class BackfillJobPayload(BaseModel):
    """A single backfill job — one chunk of a gap range.

    ``extra="allow"`` keeps the wire format forward-compatible.
    """

    model_config = ConfigDict(extra="allow")

    id: str | None = None
    """UUID4 — unique job identifier, also used as the Kafka message key."""

    channel_id: int | None = None
    """Numeric Telegram peer ID (channel) — negative for channels."""

    from_id: int | None = None
    """First message ID to fetch (inclusive — the start of the gap)."""

    to_id: int | None = None
    """Last message ID to fetch (inclusive — the end of the gap)."""

    priority: int | None = None
    """Lower values = higher urgency.  Computed from recency + gap size."""

    created_at: str | None = None
    """ISO 8601 timestamp when the gap was detected."""
