doeff-time 0.1.0__tar.gz

doeff_time-0.1.0/.gitignore

@@ -0,0 +1,145 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+# macOS debug symbols for the compiled extension above: build output that
+# embeds the builder's absolute paths, so it must not be distributed either.
+*.dSYM/
+.Python
+env/
+venv/
+.venv/
+ENV/
+env.bak/
+venv.bak/
+.env
+.env.*
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# docs の site(make docs-site・mkdocs build の出力)
+/site/
+
+# Testing
+.pytest_cache/
+.coverage
+.coverage.*
+coverage.xml
+*.cover
+.hypothesis/
+htmlcov/
+.tox/
+
+# IDE
+# Generated by Eclipse buildship and machine-specific: embeds the local Java home
+# and toolchain paths. The gradle build does not read it.
+ide-plugins/pycharm/.settings/org.eclipse.buildship.core.prefs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# UV
+!uv.lock
+.venv/
+
+# Ruff
+.ruff_cache/
+
+# MyPy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Generated logs, traces, and local databases
+.doeff-lint.jsonl
+.doeff-flow/
+*.jsonl
+# 旧い版の coordinator の置き場の log(版上げの下見の検 test_deployed_state_upgrade.hy が読む fixture — 生成された log ではない)
+!packages/doeff-cluster/tests/fixtures/coordinator_state_*/wal/wal.jsonl
+# codex の app-server の実物の行を録った物(行の分類の検 packages/doeff-codex/tests/test_lines.hy が読む fixture — 生成された log ではない)
+!packages/doeff-codex/tests/recorded/codex-*/*.jsonl
+*.db
+*.db-journal
+*.db-shm
+*.db-wal
+*.sqlite
+*.sqlite-journal
+*.sqlite-shm
+*.sqlite-wal
+*.sqlite3
+*.sqlite3-journal
+*.sqlite3-shm
+*.sqlite3-wal
+None
+Untitled
+
+# Local agent and browser automation state
+.agent-home/
+.playwright-mcp/
+.claude/settings.local.json
+.claude/skills/install-vscode-plugin/
+.agents/skills/install-vscode-plugin/
+
+# Accidental desktop helper bundle captured at repository root
+/server.js
+
+# Rust build artifacts
+rust/**/target/
+packages/**/target/
+
+# Local deploy keys
+proboscis_doeff_deploy
+proboscis_doeff_deploy.pub
+
+# Worktrees and orchestration
+.git-worktrees/
+.orch/
+.sisyphus/
+VAULT
+
+# Override global gitignore for examples
+!examples/
+ORCH_PROMPT.md
+.worktrees/
+
+# Local workspace artifacts
+# Repo-root scratch directory only. A `python/` directory inside a package
+# (e.g. packages/doeff-indexer/python/) is NOT covered by this rule.
+/python/
+
+
+# 設計記録は repo に入れる — global の除外(`artifacts` の dir・`*.html`・`*.svg`)を打ち消す
+# (打ち消しは dir を先に戻さないと中身に効かない)
+!docs/design/*/artifacts/
+!docs/design/**
+# 書き込みロックだけは入れない(道具が作る一時 file — 打ち消しの後に置く)
+docs/design/*/.records.lock
+
+# Repository-owned Zenn article visuals (override global image ignores)
+!/images/zenn-use-cases-v0/*.png
+# 記事が参照する採用画像は generated/ の下に在る(上の行は直下だけに効き、2026-09-16 の 47 枚は入らなかった)
+!/images/zenn-use-cases-v0/generated/
+!/images/zenn-use-cases-v0/generated/*.png
+# 手で書いた図の正本(global の `*.svg` の除外を打ち消す)
+!/publications/zenn-use-cases-v0/visuals/*.svg

doeff_time-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,49 @@
+# 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/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "doeff-time"
+version = "0.1.0"
+description = "Provider-agnostic time effects for doeff"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "doeff>=0.8.0,<0.9",
+    "doeff-core-effects>=0.8.0,<0.9",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/doeff_time"]
+
+[tool.uv.sources]
+doeff = { workspace = true }

doeff_time-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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