doeff-time 0.1.0__py3-none-any.whl

doeff_time/__init__.py

@@ -0,0 +1,34 @@
+"""Public API for doeff-time."""
+
+from doeff_time._internals.sim_clock import SimClock as SimClock
+from doeff_time.effects.time import Delay as Delay
+from doeff_time.effects.time import DelayEffect as DelayEffect
+from doeff_time.effects.time import GetMonotonic as GetMonotonic
+from doeff_time.effects.time import GetMonotonicEffect as GetMonotonicEffect
+from doeff_time.effects.time import GetTime as GetTime
+from doeff_time.effects.time import GetTimeEffect as GetTimeEffect
+from doeff_time.effects.time import RaceOutcome as RaceOutcome
+from doeff_time.effects.time import RaceWithin as RaceWithin
+from doeff_time.effects.time import RaceWithinEffect as RaceWithinEffect
+from doeff_time.effects.time import ScheduleAt as ScheduleAt
+from doeff_time.effects.time import ScheduleAtEffect as ScheduleAtEffect
+from doeff_time.effects.time import SetTime as SetTime
+from doeff_time.effects.time import SetTimeEffect as SetTimeEffect
+from doeff_time.effects.time import TicksOutcome as TicksOutcome
+from doeff_time.effects.time import WaitTicks as WaitTicks
+from doeff_time.effects.time import WaitTicksEffect as WaitTicksEffect
+from doeff_time.effects.time import WaitUntil as WaitUntil
+from doeff_time.effects.time import WaitUntilEffect as WaitUntilEffect
+from doeff_time.effects.time import WaitWithin as WaitWithin
+from doeff_time.effects.time import WaitWithinEffect as WaitWithinEffect
+from doeff_time.effects.time import delay as delay
+from doeff_time.effects.time import get_monotonic as get_monotonic
+from doeff_time.effects.time import get_time as get_time
+from doeff_time.effects.time import schedule_at as schedule_at
+from doeff_time.effects.time import set_time as set_time
+from doeff_time.effects.time import wait_until as wait_until
+from doeff_time.effects.time import wait_within as wait_within
+from doeff_time.epoch_ms import epoch_ms_of as epoch_ms_of
+from doeff_time.handlers.async_time import async_time_handler as async_time_handler
+from doeff_time.handlers.sim_time import sim_time_handler as sim_time_handler
+from doeff_time.handlers.sync_time import sync_time_handler as sync_time_handler

doeff_time/_internals/__init__.py

@@ -0,0 +1,10 @@
+"""Internal helpers for simulated time."""
+
+from .sim_clock import SimClock
+from .time_queue import TimeQueue, TimeQueueEntry
+
+__all__ = [
+    "SimClock",
+    "TimeQueue",
+    "TimeQueueEntry",
+]

doeff_time/_internals/deadline.py

@@ -0,0 +1,14 @@
+"""The value a timed wait's deadline completes with."""
+
+
+class _DeadlinePassed:
+    """The deadline of a timed wait passed. Told apart from every future's value by identity (a future may
+    complete with None — RaceWithin), so the clock handlers complete their deadline with this, never None."""
+
+    __slots__ = ()
+
+    def __repr__(self) -> str:
+        return "DEADLINE_PASSED"
+
+
+DEADLINE_PASSED = _DeadlinePassed()

doeff_time/_internals/sim_clock.py

@@ -0,0 +1,24 @@
+"""Virtual monotonic clock for simulation handlers."""
+
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+from .validation import ensure_aware_datetime
+
+
+@dataclass
+class SimClock:
+    current_time: datetime = datetime(1970, 1, 1, tzinfo=timezone.utc)
+
+    def __post_init__(self) -> None:
+        self.current_time = ensure_aware_datetime(self.current_time, name="current_time")
+
+    def advance_to(self, target_time: datetime) -> datetime:
+        target = ensure_aware_datetime(target_time, name="target_time")
+        self.current_time = max(self.current_time, target)
+        return self.current_time
+
+    def set_time(self, new_time: datetime) -> datetime:
+        self.current_time = ensure_aware_datetime(new_time, name="new_time")
+        return self.current_time

doeff_time/_internals/time_queue.py

@@ -0,0 +1,68 @@
+"""Min-heap queue of time-ordered promises."""
+
+import heapq
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+
+from doeff_core_effects.scheduler import Promise
+
+from doeff_time._internals.validation import ensure_aware_datetime
+
+# ``Promise`` is generic to the type checker but not subscriptable at runtime.
+
+
+@dataclass(frozen=True)
+class TimeQueueEntry:
+    time: datetime
+    sequence: int
+    promise: "Promise[Any]"
+    # The value the clock completes ``promise`` with (a RaceWithin deadline's DEADLINE_PASSED, else None).
+    answer: Any = None
+
+
+class TimeQueue:
+    def __init__(self) -> None:
+        self._mut_sequence = 0
+        self._mut_items: "list[tuple[datetime, int, Promise[Any], Any]]" = []  # noqa: UP037
+        # Sequences of entries withdrawn before their time (a timed wait whose future won —
+        # agora-redesign #2618). Dropped lazily when they reach the head, so withdrawing is O(1)
+        # and the clock never advances to a deadline nobody waits for.
+        self._mut_withdrawn: set[int] = set()
+        # Sequences still in the heap and not withdrawn — answers "is it still queued?" in O(1).
+        self._mut_queued: set[int] = set()
+
+    def push(self, time: datetime, promise: "Promise[Any]", answer: Any = None) -> int:
+        """Queue ``promise`` to be completed with ``answer`` at ``time``; answers the entry's sequence (for ``withdraw``)."""
+        target_time = ensure_aware_datetime(time, name="time")
+        self._mut_sequence += 1
+        heapq.heappush(self._mut_items, (target_time, self._mut_sequence, promise, answer))
+        self._mut_queued.add(self._mut_sequence)
+        return self._mut_sequence
+
+    def withdraw(self, sequence: int) -> None:
+        """Drop a queued entry before its time (no-op when it was already popped)."""
+        if sequence in self._mut_queued:
+            self._mut_queued.discard(sequence)
+            self._mut_withdrawn.add(sequence)
+            self._drop_withdrawn_head()
+
+    def _drop_withdrawn_head(self) -> None:
+        """Keep the head a live entry, so ``pop`` / ``empty`` never see a withdrawn deadline."""
+        while self._mut_items and self._mut_items[0][1] in self._mut_withdrawn:
+            _, sequence, _, _ = heapq.heappop(self._mut_items)
+            self._mut_withdrawn.discard(sequence)
+
+    def pop(self) -> TimeQueueEntry:
+        self._drop_withdrawn_head()
+        time, sequence, promise, answer = heapq.heappop(self._mut_items)
+        self._mut_queued.discard(sequence)
+        self._drop_withdrawn_head()
+        return TimeQueueEntry(time=time, sequence=sequence, promise=promise, answer=answer)
+
+    def empty(self) -> bool:
+        self._drop_withdrawn_head()
+        return not self._mut_items
+
+    def __len__(self) -> int:
+        return len(self._mut_queued)

doeff_time/_internals/validation.py

@@ -0,0 +1,12 @@
+"""Internal validation helpers for doeff-time."""
+
+
+from datetime import datetime
+
+
+def ensure_aware_datetime(value: datetime, *, name: str) -> datetime:
+    if not isinstance(value, datetime):
+        raise TypeError(f"{name} must be datetime, got {type(value).__name__}")
+    if value.tzinfo is None:
+        raise ValueError(f"{name} must be timezone-aware datetime")
+    return value

doeff_time/effects/__init__.py

@@ -0,0 +1,29 @@
+"""Public time effects for doeff-time."""
+
+from doeff_time.effects.time import Delay as Delay
+from doeff_time.effects.time import DelayEffect as DelayEffect
+from doeff_time.effects.time import GetMonotonic as GetMonotonic
+from doeff_time.effects.time import GetMonotonicEffect as GetMonotonicEffect
+from doeff_time.effects.time import GetTime as GetTime
+from doeff_time.effects.time import GetTimeEffect as GetTimeEffect
+from doeff_time.effects.time import RaceOutcome as RaceOutcome
+from doeff_time.effects.time import RaceWithin as RaceWithin
+from doeff_time.effects.time import RaceWithinEffect as RaceWithinEffect
+from doeff_time.effects.time import ScheduleAt as ScheduleAt
+from doeff_time.effects.time import ScheduleAtEffect as ScheduleAtEffect
+from doeff_time.effects.time import SetTime as SetTime
+from doeff_time.effects.time import SetTimeEffect as SetTimeEffect
+from doeff_time.effects.time import TicksOutcome as TicksOutcome
+from doeff_time.effects.time import WaitTicks as WaitTicks
+from doeff_time.effects.time import WaitTicksEffect as WaitTicksEffect
+from doeff_time.effects.time import WaitUntil as WaitUntil
+from doeff_time.effects.time import WaitUntilEffect as WaitUntilEffect
+from doeff_time.effects.time import WaitWithin as WaitWithin
+from doeff_time.effects.time import WaitWithinEffect as WaitWithinEffect
+from doeff_time.effects.time import delay as delay
+from doeff_time.effects.time import get_monotonic as get_monotonic
+from doeff_time.effects.time import get_time as get_time
+from doeff_time.effects.time import schedule_at as schedule_at
+from doeff_time.effects.time import set_time as set_time
+from doeff_time.effects.time import wait_until as wait_until
+from doeff_time.effects.time import wait_within as wait_within

doeff_time/effects/time.py

@@ -0,0 +1,261 @@
+"""Provider-agnostic time effects."""
+
+
+import math
+from dataclasses import dataclass
+from datetime import datetime
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
+
+from doeff import EffectBase
+from doeff_time._internals.validation import ensure_aware_datetime
+
+if TYPE_CHECKING:
+    from doeff_core_effects.scheduler import Future, Task
+
+_T = TypeVar("_T")
+
+
+def _coerce_finite_float(value: float, *, name: str) -> float:
+    if not isinstance(value, (int, float)):
+        raise TypeError(f"{name} must be float, got {type(value).__name__}")
+    coerced = float(value)
+    if math.isnan(coerced) or math.isinf(coerced):
+        raise ValueError(f"{name} must be finite, got {value!r}")
+    return coerced
+
+
+@dataclass(frozen=True)
+class DelayEffect(EffectBase):
+    """Sleep for a duration in seconds."""
+
+    seconds: float
+
+    def __post_init__(self) -> None:
+        seconds = _coerce_finite_float(self.seconds, name="seconds")
+        if seconds < 0.0:
+            raise ValueError("seconds must be >= 0.0")
+        object.__setattr__(self, "seconds", seconds)
+
+
+@dataclass(frozen=True)
+class WaitUntilEffect(EffectBase):
+    """Wait until a specific timezone-aware datetime."""
+
+    target: datetime
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "target", ensure_aware_datetime(self.target, name="target"))
+
+
+@dataclass(frozen=True)
+class GetTimeEffect(EffectBase):
+    """Read current timezone-aware datetime."""
+
+
+@dataclass(frozen=True)
+class GetMonotonicEffect(EffectBase):
+    """Read monotonic seconds as a float.
+
+    Only the difference between two readings is meaningful (durations,
+    deadlines inside one process). Unlike ``GetTime`` it never jumps backwards
+    with wall-clock adjustments. The origin is handler-defined: wall-clock
+    handlers answer ``time.monotonic()``; ``sim_time_handler`` answers the
+    virtual clock's POSIX timestamp.
+    """
+
+
+@dataclass(frozen=True)
+class ScheduleAtEffect(EffectBase):
+    """Schedule a program for execution at a specific timezone-aware datetime."""
+
+    time: datetime
+    program: Any
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "time", ensure_aware_datetime(self.time, name="time"))
+
+
+@dataclass(frozen=True)
+class WaitWithinEffect(EffectBase, Generic[_T]):
+    """Wait for a scheduler future for at most ``seconds``.
+
+    Answers the future's value, or ``None`` when ``seconds`` pass first — so the
+    future's producer must not complete it with ``None``. One effect replaces the
+    "spawn a sleeping timer task, Race it, cancel it" pattern: the clock handler
+    owns the deadline (``sim_time_handler`` puts it on its virtual time queue and
+    drops it when the future wins — no task is spawned), which keeps a timed wait
+    as cheap as a Delay (agora-redesign #2618).
+
+    ``park`` is for an *external* promise that in-run code completes (doeff-records'
+    memory-store bell, rung by a synchronous write): the race against the deadline
+    parks like ``Wait(future, priority=PRIORITY_IDLE)`` instead of shielding the sim
+    clock, so virtual time can reach the deadline while the promise is pending. With
+    the default (``False``) a pending external promise holds the clock, and the
+    deadline cannot pass before it completes (agora-redesign #3054).
+    """
+
+    future: "Future[_T]"
+    seconds: float
+    park: bool = False
+
+    def __post_init__(self) -> None:
+        seconds = _coerce_finite_float(self.seconds, name="seconds")
+        if seconds < 0.0:
+            raise ValueError("seconds must be >= 0.0")
+        if not isinstance(self.park, bool):
+            raise TypeError(f"park must be bool, got {type(self.park).__name__}")
+        object.__setattr__(self, "seconds", seconds)
+
+
+@dataclass(frozen=True)
+class RaceOutcome(Generic[_T]):
+    """The answer of RaceWithin: ``value`` = the value of the first of the futures to complete (None when the
+    deadline passed first) and ``timed_out`` = whether the deadline passed first."""
+
+    value: "_T | None"
+    timed_out: bool
+
+
+@dataclass(frozen=True)
+class RaceWithinEffect(EffectBase, Generic[_T]):
+    """Wait for the first of several scheduler futures or tasks for at most ``seconds``.
+
+    WaitWithin for a Race: answers ``RaceOutcome(value, False)`` with the value of the first of ``futures``
+    to complete (a failure or a cancellation is raised, as ``Race`` does), or ``RaceOutcome(None, True)`` when
+    ``seconds`` pass first. A future may complete with ``None``: the deadline is told apart by ``timed_out``,
+    not by the value. One effect replaces "spawn a sleeping timer task, Race it against the futures, cancel
+    it": ``sim_time_handler`` puts the deadline on its virtual time queue and withdraws it when a future wins
+    — no task is spawned (doeff-cluster's worker tick pause races its wake bells against the next due time
+    this way). ``park`` is WaitWithin's.
+    """
+
+    futures: "tuple[Task[_T] | Future[_T], ...]"
+    seconds: float
+    park: bool = False
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.futures, tuple):
+            raise TypeError(f"futures must be a tuple, got {type(self.futures).__name__}")
+        if not self.futures:
+            raise ValueError("futures must hold at least one Task or Future (a bare deadline is a Delay)")
+        seconds = _coerce_finite_float(self.seconds, name="seconds")
+        if seconds < 0.0:
+            raise ValueError("seconds must be >= 0.0")
+        if not isinstance(self.park, bool):
+            raise TypeError(f"park must be bool, got {type(self.park).__name__}")
+        object.__setattr__(self, "seconds", seconds)
+
+
+@dataclass(frozen=True)
+class TicksOutcome(Generic[_T]):
+    """The answer of WaitTicks: ``value`` = the future's value (None when the ticks ran out first) and
+    ``passed`` = how many ticks passed before the answer (0 to ``count``)."""
+
+    value: "_T | None"
+    passed: int
+
+
+@dataclass(frozen=True)
+class WaitTicksEffect(EffectBase, Generic[_T]):
+    """Wait for a scheduler future across a run of ``count`` ticks spaced ``every`` seconds, without waking
+    at each tick.
+
+    The ticks are at ``every``, ``2 * every`` … ``count * every`` seconds from now. Answers
+    ``TicksOutcome(value, passed)``: the future's value when it completes first (``passed`` = the ticks
+    that passed before it), or ``TicksOutcome(None, count)`` when the last tick passes first.
+
+    The order at a tick instant is that of a waiter that re-registers ``WaitWithin(future, every)`` at
+    each tick (agora-redesign #3066): tick k counts as passed before any other timer due at the same
+    instant that was registered after tick k-1 passed, and after one registered before it.
+    ``sim_time_handler`` keeps that order by re-queueing tick k+1 on its virtual time queue the moment
+    tick k is taken off it — the waiting task is not woken at the ticks. ``park`` is WaitWithin's.
+    """
+
+    future: "Future[_T]"
+    every: float
+    count: int
+    park: bool = False
+
+    def __post_init__(self) -> None:
+        every = _coerce_finite_float(self.every, name="every")
+        if every <= 0.0:
+            raise ValueError("every must be > 0.0")
+        if isinstance(self.count, bool) or not isinstance(self.count, int):
+            raise TypeError(f"count must be int, got {type(self.count).__name__}")
+        if self.count < 1:
+            raise ValueError("count must be >= 1")
+        if not isinstance(self.park, bool):
+            raise TypeError(f"park must be bool, got {type(self.park).__name__}")
+        object.__setattr__(self, "every", every)
+
+
+@dataclass(frozen=True)
+class SetTimeEffect(EffectBase):
+    """Set current timezone-aware datetime (simulation handlers may support this effect)."""
+
+    time: datetime
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "time", ensure_aware_datetime(self.time, name="time"))
+
+
+def delay(seconds: float) -> DelayEffect:
+    return DelayEffect(seconds=seconds)
+
+
+def wait_until(target: datetime) -> WaitUntilEffect:
+    return WaitUntilEffect(target=target)
+
+
+def get_time() -> GetTimeEffect:
+    return GetTimeEffect()
+
+
+def get_monotonic() -> GetMonotonicEffect:
+    return GetMonotonicEffect()
+
+
+def schedule_at(time: datetime, program: Any) -> ScheduleAtEffect:
+    return ScheduleAtEffect(time=time, program=program)
+
+
+def set_time(time: datetime) -> SetTimeEffect:
+    return SetTimeEffect(time=time)
+
+
+def wait_within(future: "Future[_T]", seconds: float, *, park: bool = False) -> "WaitWithinEffect[_T]":
+    return WaitWithinEffect(future=future, seconds=seconds, park=park)
+
+
+def Delay(seconds: float) -> EffectBase:  # noqa: N802
+    return DelayEffect(seconds=seconds)
+
+
+def WaitUntil(target: datetime) -> EffectBase:  # noqa: N802
+    return WaitUntilEffect(target=target)
+
+
+def GetTime() -> EffectBase:  # noqa: N802
+    return GetTimeEffect()
+
+
+def GetMonotonic() -> EffectBase:  # noqa: N802
+    return GetMonotonicEffect()
+
+
+def ScheduleAt(time: datetime, program: Any) -> EffectBase:  # noqa: N802
+    return ScheduleAtEffect(time=time, program=program)
+
+
+def SetTime(time: datetime) -> EffectBase:  # noqa: N802
+    return SetTimeEffect(time=time)
+
+
+def WaitWithin(future: "Future[_T]", seconds: float, *, park: bool = False) -> EffectBase:  # noqa: N802
+    return WaitWithinEffect(future=future, seconds=seconds, park=park)
+
+
+# The effects' constructors under the names the other waits use (the classes themselves — a typed answer, no wrapper).
+WaitTicks = WaitTicksEffect
+RaceWithin = RaceWithinEffect
+

doeff_time/epoch_ms.py

@@ -0,0 +1,21 @@
+"""時刻を epoch ミリ秒の整数へ換算する式の唯一の定義(GetTime の答えを、他の process や記録の刻と並べる物差しへ)。
+
+同じ刻を 2 か所が別の丸め方(四捨五入と床)で綴ると、329.6 ms に書いた刻が 329.9 ms に刻んだ後の刻より 1 ms 後に見える
+(#3855)。丸めはここの 1 つだけにし、刻を並べる所はすべてこれで綴る。
+"""
+
+from datetime import datetime, timedelta, timezone
+
+from doeff_time._internals.validation import ensure_aware_datetime
+
+_EPOCH = datetime(1970, 1, 1, tzinfo=timezone.utc)
+_ONE_MS = timedelta(milliseconds=1)
+
+
+def epoch_ms_of(at: datetime) -> int:
+    """timezone つきの時刻 → epoch ミリ秒(床へ丸める)。
+
+    timedelta の整数の割り算で求め、float を経ない(float の timestamp を 1000 倍すると 1 ms ずれることがある)。起点より前の
+    時刻も床へ丸める(1969-12-31T23:59:59.9995Z → -1)。時差の付き方が違う 2 つの時刻も同じ物差しに乗る。
+    """
+    return (ensure_aware_datetime(at, name="at") - _EPOCH) // _ONE_MS

doeff_time/handlers/__init__.py

@@ -0,0 +1,13 @@
+"""Public handlers for doeff-time."""
+
+
+from .async_time import ProtocolHandler, async_time_handler
+from .sim_time import sim_time_handler
+from .sync_time import sync_time_handler
+
+__all__ = [
+    "ProtocolHandler",
+    "async_time_handler",
+    "sim_time_handler",
+    "sync_time_handler",
+]

doeff_time/handlers/_wall_ticks.py

@@ -0,0 +1,59 @@
+"""The three timed waits on a wall clock — WaitWithin, WaitTicks (agora-redesign #3066) and RaceWithin.
+
+All race the futures against one deadline timer that completes with DEADLINE_PASSED; they differ only in
+which futures, how long the deadline is and in the answer. The async and sync handlers share this, so their
+one clause answers the three waits the same way.
+"""
+
+from doeff_core_effects.scheduler import Future, Task
+
+from doeff_time._internals.deadline import DEADLINE_PASSED
+from doeff_time.effects import (
+    RaceOutcome,
+    RaceWithinEffect,
+    TicksOutcome,
+    WaitTicksEffect,
+    WaitWithinEffect,
+)
+
+TimedWait = WaitWithinEffect[object] | WaitTicksEffect[object] | RaceWithinEffect[object]
+
+
+def timed_wait_futures(effect: TimedWait) -> "tuple[Task[object] | Future[object], ...]":
+    """What ``effect`` races against its deadline: RaceWithin's ``futures``, or the one ``future``."""
+    match effect:
+        case RaceWithinEffect():
+            return effect.futures
+        case WaitWithinEffect() | WaitTicksEffect():
+            return (effect.future,)
+
+
+def timed_wait_seconds(effect: TimedWait) -> float:
+    """How long the deadline of ``effect`` is on the wall clock: WaitWithin's and RaceWithin's ``seconds``, or
+    the time to WaitTicks' last tick."""
+    match effect:
+        case WaitWithinEffect() | RaceWithinEffect():
+            return max(0.0, effect.seconds)
+        case WaitTicksEffect():
+            return effect.every * effect.count
+
+
+def timed_wait_answer(effect: TimedWait, first: object, elapsed: float) -> object:
+    """The answer of ``effect`` once the race gave ``first`` (DEADLINE_PASSED when the deadline won) after
+    ``elapsed`` seconds: WaitWithin answers the future's value or None; RaceWithin answers it as a RaceOutcome;
+    WaitTicks answers it with the ticks that passed — a wall clock does not observe them one by one, so all of
+    them when the ticks ran out first, else the whole spacings in ``elapsed``, at most ``count``."""
+    timed_out = first is DEADLINE_PASSED
+    value = None if timed_out else first
+    match effect:
+        case WaitWithinEffect():
+            return value
+        case RaceWithinEffect():
+            return RaceOutcome(value=value, timed_out=timed_out)
+        case WaitTicksEffect():
+            passed = (
+                effect.count
+                if timed_out
+                else min(effect.count, max(0, int(elapsed // effect.every)))
+            )
+            return TicksOutcome(value=value, passed=passed)

doeff_time/handlers/async_time.py

@@ -0,0 +1,142 @@
+"""Asyncio-backed wall-clock handler for doeff-time effects."""
+
+
+import asyncio
+import time
+from collections.abc import Awaitable, Callable
+from datetime import datetime, timezone
+from typing import Any
+
+from doeff_core_effects import Await
+from doeff_core_effects.scheduler import PRIORITY_IDLE, Cancel, Race, Spawn
+
+from doeff import Pass, Transfer, do
+from doeff import handler as _program_handler
+from doeff.program import ProgramHandler
+from doeff_time._internals.deadline import DEADLINE_PASSED
+from doeff_time.effects import (
+    DelayEffect,
+    GetMonotonicEffect,
+    GetTimeEffect,
+    RaceWithinEffect,
+    ScheduleAtEffect,
+    WaitTicksEffect,
+    WaitUntilEffect,
+    WaitWithinEffect,
+)
+from doeff_time.handlers._wall_ticks import (
+    timed_wait_answer,
+    timed_wait_futures,
+    timed_wait_seconds,
+)
+
+ProtocolHandler = Callable[[Any, Any], Any]
+
+# The effects AsyncTimeRuntime.handle answers.
+AsyncTimeEffect = (
+    DelayEffect
+    | WaitUntilEffect
+    | GetTimeEffect
+    | GetMonotonicEffect
+    | WaitWithinEffect
+    | WaitTicksEffect
+    | RaceWithinEffect
+    | ScheduleAtEffect
+)
+
+
+def _utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _clock_wait(sleep: Callable[[float], Awaitable[Any]], seconds: float) -> Await:
+    """An Await whose completion time is known: the scheduler does not count
+    it as stalled until ``seconds`` have passed (agora-redesign #765). The
+    deadline is on the scheduler's clock (``time.monotonic``), not on the
+    injectable ``monotonic`` that answers GetMonotonic."""
+    return Await(sleep(seconds), deadline=time.monotonic() + seconds)
+
+
+class AsyncTimeRuntime:
+    """Runtime container for async wall-clock time effects."""
+
+    def __init__(
+        self,
+        *,
+        now: Callable[[], datetime],
+        sleep: Callable[[float], Awaitable[Any]],
+        monotonic: Callable[[], float],
+    ) -> None:
+        self._now = now
+        self._sleep = sleep
+        self._monotonic = monotonic
+
+    @do
+    def _expire_after(self, seconds: float):
+        """The deadline of a timed wait (WaitWithin・WaitTicks・RaceWithin): sleep ``seconds`` on the wall clock, then
+        answer DEADLINE_PASSED (a future may complete with None — RaceWithin)."""
+        yield _clock_wait(self._sleep, max(0.0, seconds))
+        return DEADLINE_PASSED
+
+    @do
+    def handle(self, effect: AsyncTimeEffect, k: Any):
+        # The annotation lets the VM skip this handler for every other effect, instead of
+        # calling it to Pass each one (agora card ki-1841b724d061 — every effect a records
+        # request sends past the clock cost a call here).
+        # Every clause performs its final Transfer/Pass from THIS frame.
+        # Delegating to a sub-@do that transfers (the pre-2026-07-14 shape)
+        # leaves this frame suspended mid-`yield` forever, pinning the
+        # Task handle and defeating the scheduler's terminal-entry sweep
+        # (ADR-DOE-CORE-EFFECTS-002).
+        if isinstance(effect, DelayEffect):
+            yield _clock_wait(self._sleep, max(0.0, effect.seconds))
+            return (yield Transfer(k, None))
+        if isinstance(effect, WaitUntilEffect):
+            wait_seconds = max(0.0, (effect.target - self._now()).total_seconds())
+            yield _clock_wait(self._sleep, wait_seconds)
+            return (yield Transfer(k, None))
+        if isinstance(effect, GetTimeEffect):
+            return (yield Transfer(k, self._now()))
+        if isinstance(effect, GetMonotonicEffect):
+            return (yield Transfer(k, float(self._monotonic())))
+        if isinstance(effect, (WaitWithinEffect, WaitTicksEffect, RaceWithinEffect)):
+            # The deadline is a daemon task sleeping on the wall clock, raced against the future(s) and
+            # cancelled afterwards (daemon: abandoning it at root return is its lifecycle — #501).
+            # WaitTicks' deadline is its last tick (agora-redesign #3066).
+            started = float(self._monotonic())
+            timer = yield Spawn(self._expire_after(timed_wait_seconds(effect)), daemon=True)
+            try:
+                first = yield Race(*timed_wait_futures(effect), timer, priority=PRIORITY_IDLE if effect.park else None)
+            finally:
+                yield Cancel(timer)
+            return (yield Transfer(k, timed_wait_answer(effect, first, float(self._monotonic()) - started)))
+        if isinstance(effect, ScheduleAtEffect):
+            wait_seconds = max(0.0, (effect.time - self._now()).total_seconds())
+            sleep = self._sleep
+
+            @do
+            def deferred():
+                yield _clock_wait(sleep, wait_seconds)
+                # Wait(task) answers the scheduled program's value (agora-redesign #1159).
+                return (yield effect.program)
+
+            # Resume the caller with the spawned Task (same contract as
+            # sim_time_handler) so failures of the deferred program can be
+            # observed via Wait/Gather instead of vanishing on an unwatched
+            # task (#503).
+            task = yield Spawn(deferred())
+            return (yield Transfer(k, task))
+        yield Pass(effect, k)
+
+
+def async_time_handler(
+    *,
+    now: Callable[[], datetime] = _utc_now,
+    sleep: Callable[[float], Awaitable[Any]] = asyncio.sleep,
+    monotonic: Callable[[], float] = time.monotonic,
+) -> ProgramHandler:
+    """Return a protocol handler for wall-clock async time semantics."""
+
+    runtime = AsyncTimeRuntime(now=now, sleep=sleep, monotonic=monotonic)
+    return _program_handler(runtime.handle)
+

doeff_time/handlers/sim_time.py

@@ -0,0 +1,328 @@
+"""Virtual-clock simulation handler for doeff-time effects."""
+
+
+from collections.abc import Callable
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+from doeff_core_effects import WriterTellEffect
+from doeff_core_effects.scheduler import (
+    PRIORITY_IDLE,
+    CompletePromise,
+    CreatePromise,
+    Future,
+    Race,
+    Spawn,
+    Task,
+    Wait,
+)
+
+from doeff import Pass, Transfer, do
+from doeff import handler as _program_handler
+from doeff.program import ProgramHandler
+from doeff_time._internals import SimClock, TimeQueue
+from doeff_time._internals.deadline import DEADLINE_PASSED
+from doeff_time.effects import (
+    DelayEffect,
+    GetMonotonicEffect,
+    GetTimeEffect,
+    RaceOutcome,
+    RaceWithinEffect,
+    ScheduleAtEffect,
+    SetTimeEffect,
+    TicksOutcome,
+    WaitTicksEffect,
+    WaitUntilEffect,
+    WaitWithinEffect,
+)
+
+ProtocolHandler = Callable[[Any, Any], Any]
+LogFormatter = Callable[[datetime, Any], str]
+EPOCH_UTC = datetime(1970, 1, 1, tzinfo=timezone.utc)
+#: The virtual clock's resolution (datetime keeps microseconds).
+CLOCK_TICK = timedelta(microseconds=1)
+
+
+def _delay_span(seconds: float) -> timedelta:
+    """How far a Delay moves the virtual clock: a positive delay moves it by at least one tick.
+
+    ``timedelta(seconds=s)`` rounds to whole microseconds, so a positive delay below half a
+    microsecond became zero and the clock did not move. A wait loop that sleeps "the rest of
+    its timeout" (e.g. doeff_records.watching.wait-for-changes) then slept the same sub-tick
+    remainder forever without advancing virtual time (agora-redesign #675, 2026-09-26: the
+    remainder 7.2e-08 s after float drift). A real sleep of a positive duration always lets at
+    least that much time pass, so the sim rounds such a delay up to one tick.
+    """
+    span = timedelta(seconds=seconds)
+    if seconds > 0 and span <= timedelta(0):
+        return CLOCK_TICK
+    return span
+
+
+class _TickRun:
+    """A WaitTicks waiter's ticks on the virtual time queue (agora-redesign #3066): the spacing and the number
+    of ticks, how many have passed, and the sequence of the tick queued now (withdrawn when the future wins).
+    The clock driver advances it as each tick is taken off the queue; the waiting task reads ``passed``
+    once it is answered."""
+
+    def __init__(self, every: timedelta, count: int) -> None:
+        self.every = every
+        self.count = count
+        self._mut_passed = 0
+        self._mut_sequence = 0
+
+    @property
+    def passed(self) -> int:
+        return self._mut_passed
+
+    @property
+    def sequence(self) -> int:
+        return self._mut_sequence
+
+    def queued(self, sequence: int) -> None:
+        """Remember the sequence of the tick just queued."""
+        self._mut_sequence = sequence
+
+    def tick(self) -> bool:
+        """Count a tick taken off the queue; answers whether it was the last one."""
+        self._mut_passed += 1
+        return self._mut_passed >= self.count
+
+
+class SimTimeRuntime:
+    """Runtime state for virtual-clock interpretation."""
+
+    def __init__(
+        self,
+        *,
+        clock: SimClock,
+        log_formatter: LogFormatter | None,
+    ) -> None:
+        self._clock = clock
+        self._time_queue = TimeQueue()
+        # Queued ticks of WaitTicks waiters, by queue sequence: such an entry's promise is the waiter's
+        # deadline, completed only at its last tick (agora-redesign #3066).
+        self._mut_tick_runs: dict[int, _TickRun] = {}
+        self._mut_driver_running = False
+        self._log_formatter = log_formatter
+        self._mut_forwarding_tell = False
+        self._handler: ProtocolHandler = self.handle
+
+    @do
+    def _clock_driver(self):
+        """Idle-priority daemon that advances time when normal tasks are parked.
+
+        A WaitTicks tick that is not the last is not completed: the next tick is queued the moment
+        this one is taken off — where a waiter re-registering WaitWithin at each tick would queue it,
+        since no other task runs between the pop and that waiter's re-registration — and the waiting
+        task is not woken (agora-redesign #3066)."""
+
+        try:
+            while not self._time_queue.empty():
+                entry = self._time_queue.pop()
+                self._clock.advance_to(entry.time)
+                if entry.sequence in self._mut_tick_runs:
+                    run = self._mut_tick_runs.pop(entry.sequence)
+                    if not run.tick():
+                        sequence = self._time_queue.push(entry.time + run.every, entry.promise)
+                        run.queued(sequence)
+                        self._mut_tick_runs[sequence] = run
+                        continue
+                yield CompletePromise(entry.promise, entry.answer)
+        finally:
+            self._mut_driver_running = False
+
+    @do
+    def _ensure_clock_driver(self):
+        if self._mut_driver_running:
+            return None
+        self._mut_driver_running = True
+        # daemon=True carries two contracts:
+        # - #501: the driver's final IDLE resume (queued right after its
+        #   last CompletePromise) is routinely abandoned when the root body
+        #   returns first — that is this daemon's lifecycle, not lost work,
+        #   so it must not trip the root close-out diagnostic.
+        # - #505: daemon tasks are the only tasks the scheduler's
+        #   PRIORITY_EXTERNAL_WAIT shield may starve, which is exactly what
+        #   keeps this driver from advancing sim time past a pending
+        #   external completion.
+        yield Spawn(self._clock_driver(), priority=PRIORITY_IDLE, daemon=True)
+        return None
+
+    @do
+    def _wait_for_time(self, target_time: datetime):
+        promise = yield CreatePromise()
+        self._time_queue.push(target_time, promise)
+        _ = yield self._ensure_clock_driver()
+        yield Wait(promise.future)
+
+    @do
+    def _wait_within(self, future: "Future[object]", seconds: float, park: bool):
+        """Answer ``future``'s value, or None once ``seconds`` of virtual time pass first.
+
+        The deadline is a promise on this handler's time queue (like a Delay) raced against the
+        future — no timer task is spawned, and a deadline the future beat is withdrawn from the
+        queue so the clock driver never advances to it (agora-redesign #2618). ``park`` races
+        an external promise without shielding the clock driver, so the deadline can pass while
+        the promise is pending (agora-redesign #3054).
+        """
+        deadline = yield CreatePromise()
+        sequence = self._time_queue.push(self._clock.current_time + _delay_span(seconds), deadline)
+        _ = yield self._ensure_clock_driver()
+        try:
+            first = yield Race(future, deadline.future, priority=PRIORITY_IDLE if park else None)
+        finally:
+            self._time_queue.withdraw(sequence)
+        return first
+
+    @do
+    def _race_within(self, futures: "tuple[Task[object] | Future[object], ...]", seconds: float, park: bool):
+        """Answer the first of ``futures`` to complete, or the deadline once ``seconds`` of virtual time pass
+        first — as a RaceOutcome.
+
+        WaitWithin's deadline (no timer task — withdrawn when a future wins) raced against several futures.
+        The clock driver completes it with DEADLINE_PASSED, so a future that completes with None is not
+        taken for the deadline.
+        """
+        deadline = yield CreatePromise()
+        sequence = self._time_queue.push(self._clock.current_time + _delay_span(seconds), deadline, answer=DEADLINE_PASSED)
+        _ = yield self._ensure_clock_driver()
+        try:
+            first = yield Race(*futures, deadline.future, priority=PRIORITY_IDLE if park else None)
+        finally:
+            self._time_queue.withdraw(sequence)
+        timed_out = first is DEADLINE_PASSED
+        return RaceOutcome(value=None if timed_out else first, timed_out=timed_out)
+
+    @do
+    def _wait_ticks(self, future: "Future[object]", every: float, count: int, park: bool):
+        """Answer ``future``'s value, or None once ``count`` ticks spaced ``every`` seconds pass first,
+        with how many ticks passed (agora-redesign #3066).
+
+        One tick at a time is on the time queue: the clock driver takes it off and queues the next
+        one at once, without waking this task (see _clock_driver), so a tick instant orders against
+        the other timers as if this task re-registered WaitWithin at each tick. The last tick
+        completes the deadline. A tick the future beat is withdrawn, as WaitWithin's deadline.
+        """
+        deadline = yield CreatePromise()
+        run = _TickRun(_delay_span(every), count)
+        sequence = self._time_queue.push(self._clock.current_time + run.every, deadline)
+        run.queued(sequence)
+        self._mut_tick_runs[sequence] = run
+        _ = yield self._ensure_clock_driver()
+        try:
+            first = yield Race(future, deadline.future, priority=PRIORITY_IDLE if park else None)
+        finally:
+            self._time_queue.withdraw(run.sequence)
+            if run.sequence in self._mut_tick_runs:
+                del self._mut_tick_runs[run.sequence]
+        return TicksOutcome(value=first, passed=run.passed)
+
+    def _timed_wait(self, effect: WaitWithinEffect[object] | WaitTicksEffect[object] | RaceWithinEffect[object]):
+        """The Program that answers one of the timed waits (a sub-program that completes before the Transfer)."""
+        match effect:
+            case WaitWithinEffect():
+                return self._wait_within(effect.future, effect.seconds, effect.park)
+            case WaitTicksEffect():
+                return self._wait_ticks(effect.future, effect.every, effect.count, effect.park)
+            case RaceWithinEffect():
+                return self._race_within(effect.futures, effect.seconds, effect.park)
+
+    @do
+    def handle(
+        self,
+        effect: WriterTellEffect
+        | DelayEffect
+        | WaitUntilEffect
+        | GetTimeEffect
+        | GetMonotonicEffect
+        | ScheduleAtEffect
+        | SetTimeEffect
+        | WaitWithinEffect
+        | WaitTicksEffect
+        | RaceWithinEffect,
+        k: Any,
+    ):
+        # The annotation is the clause list below: the VM skips this handler for
+        # every other effect without entering Python (doeff_vm._effect_types),
+        # the same as the trailing Pass.
+        # Every clause performs its final Transfer/Pass from THIS frame.
+        # Delegating to a sub-@do that transfers (the pre-2026-07-14 shape)
+        # leaves this frame suspended mid-`yield` forever, pinning the
+        # Task handle and defeating the scheduler's terminal-entry sweep
+        # (ADR-DOE-CORE-EFFECTS-002). Sub-programs that COMPLETE before
+        # the Transfer (_wait_for_time, _ensure_clock_driver) are fine.
+        if (
+            isinstance(effect, WriterTellEffect)
+            and self._log_formatter is not None
+            and not self._mut_forwarding_tell
+        ):
+            formatted = self._log_formatter(self._clock.current_time, effect.msg)
+            self._mut_forwarding_tell = True
+            try:
+                result = yield WriterTellEffect(formatted)
+            finally:
+                self._mut_forwarding_tell = False
+            return (yield Transfer(k, result))
+        if isinstance(effect, DelayEffect):
+            target_time = self._clock.current_time + _delay_span(effect.seconds)
+            _ = yield self._wait_for_time(target_time)
+            return (yield Transfer(k, None))
+        if isinstance(effect, WaitUntilEffect):
+            target_time = max(self._clock.current_time, effect.target)
+            _ = yield self._wait_for_time(target_time)
+            return (yield Transfer(k, None))
+        if isinstance(effect, (GetTimeEffect, GetMonotonicEffect)):
+            now = self._clock.current_time
+            # GetMonotonic reads the virtual clock's POSIX timestamp: virtual
+            # time only moves through Delay/WaitUntil/SetTime, and callers use
+            # differences between readings.
+            reading = now if isinstance(effect, GetTimeEffect) else now.timestamp()
+            return (yield Transfer(k, reading))
+        if isinstance(effect, (WaitWithinEffect, WaitTicksEffect, RaceWithinEffect)):
+            answer = yield self._timed_wait(effect)
+            return (yield Transfer(k, answer))
+        if isinstance(effect, ScheduleAtEffect):
+
+            @do
+            def deferred():
+                _ = yield self._wait_for_time(effect.time)
+                # Wait(task) answers the scheduled program's value (agora-redesign #1159).
+                return (yield effect.program)
+
+            task = yield Spawn(deferred())
+            return (yield Transfer(k, task))
+        if isinstance(effect, SetTimeEffect):
+            self._clock.set_time(effect.time)
+            if not self._time_queue.empty():
+                _ = yield self._ensure_clock_driver()
+            return (yield Transfer(k, None))
+        yield Pass(effect, k)
+
+
+def sim_time_handler(
+    *,
+    start_time: datetime | None = None,
+    clock: SimClock | None = None,
+    log_formatter: LogFormatter | None = None,
+) -> ProgramHandler:
+    """Return a virtual-clock handler that delegates core concurrency effects.
+
+    Install it inside ``scheduled`` and outside every ``Spawn`` whose tasks
+    sleep on it: spawned tasks inherit the handler, so all of them share one
+    virtual clock. Time advances to the earliest pending wake-up only when no
+    normal-priority task is runnable; wake-ups at the same instant resume in
+    the order they were requested.
+
+    ``clock`` lets the caller own the ``SimClock`` so tests can read
+    ``clock.current_time`` synchronously (or move it with ``set_time`` between
+    runs). Pass either ``start_time`` or ``clock``, not both.
+    """
+
+    if clock is not None and start_time is not None:
+        raise ValueError("pass either start_time or clock, not both")
+    if clock is None:
+        clock = SimClock(EPOCH_UTC if start_time is None else start_time)
+    runtime = SimTimeRuntime(clock=clock, log_formatter=log_formatter)
+    return _program_handler(runtime._handler)
+

doeff_time/handlers/sync_time.py

@@ -0,0 +1,127 @@
+"""Blocking wall-clock handler for doeff-time effects."""
+
+
+import threading
+import time
+from collections.abc import Callable
+from datetime import datetime, timezone
+from typing import Any
+
+from doeff_core_effects.scheduler import PRIORITY_IDLE, CreateExternalPromise, Race, Spawn
+from doeff_core_effects.scheduler import Wait as WaitTask
+
+from doeff import Pass, Transfer, do
+from doeff import handler as _program_handler
+from doeff.program import ProgramHandler
+from doeff_time._internals.deadline import DEADLINE_PASSED
+from doeff_time.effects import (
+    DelayEffect,
+    GetMonotonicEffect,
+    GetTimeEffect,
+    RaceWithinEffect,
+    ScheduleAtEffect,
+    WaitTicksEffect,
+    WaitUntilEffect,
+    WaitWithinEffect,
+)
+from doeff_time.handlers._wall_ticks import (
+    timed_wait_answer,
+    timed_wait_futures,
+    timed_wait_seconds,
+)
+
+ProtocolHandler = Callable[[Any, Any], Any]
+
+
+def _utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class SyncTimeRuntime:
+    """Runtime container for sync wall-clock time effects."""
+
+    def __init__(
+        self,
+        *,
+        now: Callable[[], datetime],
+        sleep: Callable[[float], None],
+        monotonic: Callable[[], float],
+    ) -> None:
+        self._now = now
+        self._sleep = sleep
+        self._monotonic = monotonic
+
+    @do
+    def handle(self, effect: Any, k: Any):
+        # Every clause performs its final Transfer/Pass from THIS frame.
+        # Delegating to a sub-@do that transfers (the pre-2026-07-14 shape)
+        # leaves this frame suspended mid-`yield` forever, pinning the
+        # Task handle and defeating the scheduler's terminal-entry sweep
+        # (ADR-DOE-CORE-EFFECTS-002).
+        if isinstance(effect, DelayEffect):
+            self._sleep(max(0.0, effect.seconds))
+            return (yield Transfer(k, None))
+        if isinstance(effect, WaitUntilEffect):
+            self._sleep(max(0.0, (effect.target - self._now()).total_seconds()))
+            return (yield Transfer(k, None))
+        if isinstance(effect, GetTimeEffect):
+            return (yield Transfer(k, self._now()))
+        if isinstance(effect, GetMonotonicEffect):
+            return (yield Transfer(k, float(self._monotonic())))
+        if isinstance(effect, (WaitWithinEffect, WaitTicksEffect, RaceWithinEffect)):
+            # The deadline is an external promise a wall-clock timer completes (the scheduler knows
+            # when it wakes — #765), raced against the future(s); the timer is stopped afterwards.
+            # WaitTicks' deadline is its last tick (agora-redesign #3066).
+            started = float(self._monotonic())
+            seconds = timed_wait_seconds(effect)
+            deadline = yield CreateExternalPromise(deadline=time.monotonic() + seconds)
+
+            def _deadline_passed():
+                deadline.complete(DEADLINE_PASSED)
+
+            timer = threading.Timer(seconds, _deadline_passed)
+            timer.daemon = True
+            timer.start()
+            try:
+                first = yield Race(*timed_wait_futures(effect), deadline.future, priority=PRIORITY_IDLE if effect.park else None)
+            finally:
+                timer.cancel()
+            return (yield Transfer(k, timed_wait_answer(effect, first, float(self._monotonic()) - started)))
+        if isinstance(effect, ScheduleAtEffect):
+            wait_seconds = max(0.0, (effect.time - self._now()).total_seconds())
+
+            @do
+            def deferred():
+                # A timer wait: the scheduler knows when it wakes (#765).
+                ep = yield CreateExternalPromise(deadline=time.monotonic() + wait_seconds)
+
+                def _timer_done():
+                    ep.complete(None)
+
+                timer = threading.Timer(wait_seconds, _timer_done)
+                timer.daemon = True
+                timer.start()
+                yield WaitTask(ep.future)
+                # Wait(task) answers the scheduled program's value (agora-redesign #1159).
+                return (yield effect.program)
+
+            # Resume the caller with the spawned Task (same contract as
+            # sim_time_handler) so failures of the deferred program can be
+            # observed via Wait/Gather instead of vanishing on an unwatched
+            # task (#503).
+            task = yield Spawn(deferred())
+            return (yield Transfer(k, task))
+        yield Pass(effect, k)
+
+
+def sync_time_handler(
+    *,
+    now: Callable[[], datetime] = _utc_now,
+    sleep: Callable[[float], None] = time.sleep,
+    monotonic: Callable[[], float] = time.monotonic,
+) -> ProgramHandler:
+    """Return a protocol handler for blocking wall-clock time semantics."""
+
+    runtime = SyncTimeRuntime(now=now, sleep=sleep, monotonic=monotonic)
+    return _program_handler(runtime.handle)
+

doeff_time/py.typed

@@ -0,0 +1 @@
+

doeff_time-0.1.0.dist-info/METADATA

@@ -0,0 +1,58 @@
+Metadata-Version: 2.5
+Name: doeff-time
+Version: 0.1.0
+Summary: Provider-agnostic time effects for doeff
+Requires-Python: >=3.10
+Requires-Dist: doeff-core-effects<0.9,>=0.8.0
+Requires-Dist: doeff<0.9,>=0.8.0
+Description-Content-Type: text/markdown
+
+# doeff-time
+
+Provider-agnostic time effects for `doeff`.
+
+## Effects
+
+- `Delay(seconds)`
+- `WaitUntil(target: datetime)` (`target` must be timezone-aware)
+- `GetTime()`
+- `GetMonotonic()` — monotonic seconds (`float`); only differences are meaningful
+- `ScheduleAt(time: datetime, program)` (`time` must be timezone-aware) — answers the spawned `Task`;
+  `Wait(task)` answers `program`'s value, or raises its failure
+- `SetTime(time: datetime)` (for simulation handlers, `time` must be timezone-aware)
+
+## Conversions
+
+- `epoch_ms_of(at: datetime) -> int` — timezone-aware time → epoch milliseconds, floored by integer
+  `timedelta` division (no float on the way). This is the one rounding for every stamp that is laid
+  next to another stamp: two places rounding the same instant differently (round vs floor) make a
+  write at 329.6 ms look 1 ms later than a read at 329.9 ms.
+
+## Handlers
+
+- `async_time_handler()` for `asyncio` runtimes
+- `sync_time_handler()` for blocking runtimes
+- `sim_time_handler(start_time=...)` for deterministic virtual time (`start_time` is timezone-aware
+  `datetime`), or `sim_time_handler(clock=SimClock(start))` when the caller wants to read or move
+  the virtual clock outside the program (tests)
+
+### Shared contract (all three handlers)
+
+`tests/test_time_contract.hy` runs the same deftests under each handler (`:interpreters
+["async" "sync" "sim"]`): readings never go back, `Delay(d)` / `WaitUntil(t)` advance the clock by
+`d` / up to `t` (exactly on the virtual clock, with a small jitter bound on the wall clock), past
+targets return at once, other effects pass through, and `ScheduleAt` tasks run in time order and
+answer their program's value or failure through `Wait`. `SetTime` is simulation-only and stays out
+of the shared contract. Note: the scheduled program runs under the handlers outside the time
+handler, so it cannot itself perform time effects.
+
+### Virtual time contract (`sim_time_handler`)
+
+- Install inside `scheduled(...)` and outside every `Spawn` whose tasks sleep on it; spawned tasks
+  inherit the handler and share one clock.
+- Time advances to the earliest pending wake-up only when no normal-priority task is runnable, so a
+  task woken at `t` reads `t` however many scheduler steps it takes.
+- Wake-ups at the same instant resume in the order they were requested; the trace is identical on
+  the Rust scheduler (the default) and the Python one (`DOEFF_SCHEDULER=python`).
+- The run ends when the root program returns, even while daemon services are still sleeping.
+- `GetMonotonic()` answers the virtual clock's POSIX timestamp.

doeff_time-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+doeff_time/__init__.py,sha256=NYdLE7Fq_wHdsXRlRZYMMYNekBdyVOkVRSU1yk7-xzU,2110
+doeff_time/epoch_ms.py,sha256=Bo_QO4pCYjyxiQkGK1j5xQKig26uhMu1kaz930hIjDc,1116
+doeff_time/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+doeff_time/_internals/__init__.py,sha256=x6CLm0HU6ekQPaxG-hG9lYr3AR_t5gw6NGg-2rcR4AE,196
+doeff_time/_internals/deadline.py,sha256=fFeKYDnV8tYa0-IcrNtep1pU9ptNat339xmfWCOh9Kw,423
+doeff_time/_internals/sim_clock.py,sha256=3rYp861I3W292Vvtv8PbOSIXj4ccX4ef5C7TCRMlHqU,799
+doeff_time/_internals/time_queue.py,sha256=G-5KmcXJkFeteg_aeSWheOGzETv-ZisY33Uq4RYPn5k,2829
+doeff_time/_internals/validation.py,sha256=QOCZVDP42fsiRNxzTqinegiHK3TVTQ6-6_LaBcxFH3c,388
+doeff_time/effects/__init__.py,sha256=3Ih-0f41D_81jsLmlmSrF05zxhSfKrT05FhJJNItUr4,1752
+doeff_time/effects/time.py,sha256=qZrhy1WWlxsCAb-YGa5MV_785IzzEn4GTp0Y8-DQAdA,9542
+doeff_time/handlers/__init__.py,sha256=Qu3t9f1iJw4sqMYoD1coAR7PgkEHsB_l2DFaSx_ttGU,293
+doeff_time/handlers/_wall_ticks.py,sha256=-ONTYUbmd_FUFKa0rjehPJWV_vEbmzWmiEu78nTdcJY,2522
+doeff_time/handlers/async_time.py,sha256=kGIBFM_eMLQzumHuIiOfOV2QXbuehl3I0ll0ggvaEaQ,5557
+doeff_time/handlers/sim_time.py,sha256=V879gET0oJFSK2oeV4UMiFv8aVftZlxZgRwyn0M5KHM,14222
+doeff_time/handlers/sync_time.py,sha256=_a2C4cQiHBKxqpxxLKUbTnSdxTX6uUa33d5qlAwycnY,4773
+doeff_time-0.1.0.dist-info/METADATA,sha256=rNgXXz4ihxbclo7-NQP1J1enZWwbmpWeOLNMy7CZ5K8,2854
+doeff_time-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+doeff_time-0.1.0.dist-info/RECORD,,

doeff_time-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any