"""Monotonic-clock discipline for the platform lane.

Headline durations in platform rows come from a single local monotonic clock

(``time.monotonic``), never from server timestamps. GitHub computes PR

mergeability asynchronously; that settling is a measured operation, observed

by polling, so every settle result carries its own resolution bound

(``poll_quantization_ms`` = interval * 1000) the way devloop prints detection

limits — a settle measured at 10s cadence can never claim sub-10s precision.

Timeout policy (decided here, per ADR-0002): a timed-out settle did NOT

complete, so ``settled`` is false and ``elapsed_ms`` — the duration *to the

settled state* — is null (unmeasured: the state was never observed). The wall

time actually spent waiting is not discarded; it is recorded separately as

``observed_wait_ms``, which is a measured value of a different thing (how long

we watched), never a stand-in for the settle duration.

Cross-clock values (e.g. derived from a server ``Date`` header) may be

recorded for context but are never comparable to local monotonic durations;

``bounded_cross_clock`` marks them so consumers cannot mistake them for

measurements.

"""

from __future__ import annotations

import time

from typing import Any, Callable

def monotonic_ms() -> float:

    """Current local monotonic clock reading in milliseconds."""

    return time.monotonic() * 1000.0

def settle(

    poll_fn: Callable[[], Any],

    *,

    interval_s: float,

    timeout_s: float,

    clock: Callable[[], float] = time.monotonic,

    sleep: Callable[[float], None] = time.sleep,

) -> dict[str, Any]:

    """Poll ``poll_fn`` until truthy, on one monotonic clock.

    Polls immediately, then every ``interval_s`` seconds, never starting a

    poll that could only complete past ``timeout_s``. Returns:

    - ``settled``: whether ``poll_fn`` became truthy.

    - ``elapsed_ms``: clock time from start to the settling poll; ``None``

      when not settled (ADR-0002: the settle duration was never observed).

    - ``observed_wait_ms``: clock time actually spent watching (equals

      ``elapsed_ms`` when settled; the honest wait on timeout).

    - ``poll_iterations``: number of ``poll_fn`` calls.

    - ``poll_interval_s`` / ``poll_quantization_ms``: the cadence and the

      resolution bound it imposes (interval * 1000).

    ``clock``, ``sleep``, and ``poll_fn`` are injectable so tests never wait

    on real time.

    """

    if interval_s <= 0:

        raise ValueError(f"interval_s must be positive, got {interval_s!r}")

    quantization_ms = interval_s * 1000.0

    start = clock()

    iterations = 0

    while True:

        iterations += 1

        if poll_fn():

            elapsed_ms = (clock() - start) * 1000.0

            return {

                "settled": True,

                "elapsed_ms": elapsed_ms,

                "observed_wait_ms": elapsed_ms,

                "poll_iterations": iterations,

                "poll_interval_s": interval_s,

                "poll_quantization_ms": quantization_ms,

            }

        elapsed_s = clock() - start

        if elapsed_s + interval_s > timeout_s:

            return {

                "settled": False,

                "elapsed_ms": None,

                "observed_wait_ms": elapsed_s * 1000.0,

                "poll_iterations": iterations,

                "poll_interval_s": interval_s,

                "poll_quantization_ms": quantization_ms,

            }

        sleep(interval_s)

def bounded_cross_clock(value_ms: float) -> dict[str, Any]:

    """Wrap a server-clock-derived duration so it can never pose as measured.

    Cross-clock values (local monotonic vs. server Date header) carry unknown

    skew; they are recorded for narrative context only and must never enter a

    comparison with local monotonic durations.

    """

    return {

        "value_ms": value_ms,

        "cross_clock": True,

        "descriptive_only": True,

    }