"""Pure decision logic for the librarian per-query watchdog.

Split out of ``librarian_commands`` (which pulls in discord / pdf libs, so it is
not importable in the pytest-only unit job) so the one subtle part - the grace
window that stops a just-delivered result from being falsely flagged as lost -
can be unit-tested in isolation.

The watchdog polls the librarian's /query_status for each dispatched query:

* the librarian reports the uuid ``known`` while it is queued or processing,
* once the search finishes it is dropped there, so the uuid goes ``unknown``.

A result that arrives normally is removed from the pending set by the result
handler, so the watchdog never even sees it. Only a uuid that goes ``unknown``
on the librarian *and is still pending on the bot* is a lost result - but we
require it to stay that way for a grace window first, because there is always a
brief moment where the librarian has finished (uuid gone) yet the result is
still in flight / not yet rendered.
"""

WAIT = "wait"
FLAG = "flag"


def pending_verdict(known, unknown_since, now, grace_seconds):
    """Decide what to do this tick for one pending query.

    Args:
        known: did the librarian report the uuid as still known this tick?
        unknown_since: monotonic timestamp the uuid was first seen unknown, or
            None if it was known last tick.
        now: current monotonic time.
        grace_seconds: how long a uuid must stay unknown-but-pending before it
            is declared lost.

    Returns:
        (action, unknown_since) where action is WAIT or FLAG and the returned
        ``unknown_since`` is what the caller should store for the next tick.
    """
    if known:
        # Still queued/processing (or freshly back to known) - reset the clock.
        return WAIT, None
    if unknown_since is None:
        # First tick we see it gone: start the grace clock, don't flag yet - the
        # result may simply be in flight.
        return WAIT, now
    if now - unknown_since >= grace_seconds:
        # Gone for the whole grace window and still pending: the result was lost.
        return FLAG, unknown_since
    # Gone, but not long enough yet - keep waiting.
    return WAIT, unknown_since