"""
Pipeline clock.

`now()` is `datetime.now(timezone.utc)` everywhere except inside a replay run
(app/internal/replay.py), which pins it to the replayed call's own time so the
correlator's recency windows, the idle-resolve sweep and every started_at /
updated_at / resolved_at it writes behave the way they did live.

A ContextVar rather than a module global: a replay runs as a background task
alongside real uploads, and each asyncio task (and every asyncio.to_thread it
spawns) carries its own copy of the context, so a pinned clock can never leak
into a live call's pipeline.
"""
from contextvars import ContextVar
from datetime import datetime, timezone
from typing import Optional

_pinned: ContextVar[Optional[datetime]] = ContextVar("drb_clock_pinned", default=None)


def now() -> datetime:
    pinned = _pinned.get()
    return pinned if pinned is not None else datetime.now(timezone.utc)


def pin(when: Optional[datetime]):
    """Pin the clock for the current context. Returns a token for `unpin`."""
    return _pinned.set(when)


def unpin(token) -> None:
    _pinned.reset(token)