chrono-daemon 0.1.0__tar.gz

chrono_daemon-0.1.0/.github/dependabot.yml

@@ -0,0 +1,7 @@
+version: 2
+
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

chrono_daemon-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install Python
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync --dev --extra zmq --locked
+
+      - name: Check
+        run: make check
+
+      - name: Test
+        run: make test

chrono_daemon-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,39 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install Python
+        run: uv python install 3.11
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish
+
+      - name: Create GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "$GITHUB_REF_NAME" dist/* --title "$GITHUB_REF_NAME" --generate-notes

chrono_daemon-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.pyrefly_cache/
+dist/
+build/
+*.pyc

chrono_daemon-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

chrono_daemon-0.1.0/CLAUDE.md

@@ -0,0 +1,63 @@
+# CLAUDE.md — chrono-daemon
+
+Tiny anyio-based concurrency library. Four primitives: `Channel`, `Clock`
+(Wall/Sim), `Daemon`, `Supervisor`. See `docs/concepts.md` for the user-facing
+explanation and `docs/adr/` for why each piece looks the way it does.
+
+This file is the editing-rule sheet for AI agents working on this project.
+The *why* of any decision lives in an ADR, not here.
+
+## Commands
+
+```bash
+uv sync --dev
+make check    # ruff lint + format check + pyrefly
+make test     # pytest on asyncio + trio
+make all      # format + check + test
+```
+
+## Editing rules
+
+Each of these has an ADR. Don't violate them without writing a superseding
+ADR first.
+
+- **`anyio` is the only direct runtime dependency.** No `msgspec`, no
+  `structlog`, no `pydantic`. (ADR 0007.)
+- **`Channel` is the sole communication primitive on the core surface.**
+  Don't add `Topic`, pub/sub broadcast, services, RPC, or a parameter
+  system to `chrono_daemon.*`. Fanout lives at `chrono_daemon.recipes.fanout.tee` —
+  importable, but under the weaker-stability recipes namespace. (ADR 0001.)
+- **Daemons must reach for `ctx.clock.sleep(...)` or
+  `ctx.clock.wait_until(...)`** — never `anyio.sleep` directly.
+  Library-internal code must obey this so `SimClock` can intercept.
+  (ADR 0002.)
+- **`Daemon` has exactly three hooks**: `on_start`, `run`, `on_stop`. No
+  pause/resume, no lifecycle state machine. (ADR 0005.)
+- **`Channel` protocol signatures stay transport-agnostic.** Don't bake
+  in-process Python-identity or sync assumptions; future transport adapters
+  share the same surface. (ADR 0006.)
+
+## Test discipline
+
+- Every async test is parametrized over `["asyncio", "trio"]` via
+  `tests/conftest.py`. New tests must pass on both.
+- Canary: `tests/test_clock.py::test_simclock_burst_step_deterministic_order`
+  — if this fails on either backend, the rest of the system is unreliable.
+- `tests/test_integration.py` is the "would chrono-daemon replace simple_env"
+  check. Don't weaken it.
+- `tests/test_examples.py` pins the demos in `examples/`. Don't bypass it
+  by skipping; fix the demo instead.
+
+## What lives where
+
+- `src/chrono_daemon/` — the seven core modules. Each one is short and has one job.
+- `docs/concepts.md` — user-facing explanation of the four primitives.
+- `docs/adr/` — frozen-in-time decision records. Immutable once accepted;
+  add a new ADR to revise.
+- `src/chrono_daemon/recipes/` — patterns kept off the core surface but
+  importable under `chrono_daemon.recipes.*`. Weaker stability guarantees than
+  the core (see `src/chrono_daemon/recipes/__init__.py`).
+- `docs/recipes.md` — user-facing index for the above.
+- `examples/` — end-to-end demos exercised by CI (`tests/test_examples.py`).
+- `CLAUDE.md` (this file) — editing rules + commands only.
+- Top-level `README.md` — the 5-minute pitch.

chrono_daemon-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Suhwan Choi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chrono_daemon-0.1.0/Makefile

@@ -0,0 +1,23 @@
+.PHONY: check test lint format install all
+
+# Source paths that participate in lint/format/type-check.
+SRC_PATHS = src/ tests/ examples/
+
+check: lint
+	uv run pyrefly check
+
+lint:
+	uv run ruff check $(SRC_PATHS)
+	uv run ruff format --check $(SRC_PATHS)
+
+format:
+	uv run ruff format $(SRC_PATHS)
+	uv run ruff check --fix $(SRC_PATHS)
+
+test:
+	uv run pytest tests/ -v
+
+install:
+	uv sync --dev --extra zmq
+
+all: format check test

chrono_daemon-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: chrono-daemon
+Version: 0.1.0
+Summary: Tiny anyio-based concurrency primitives: Channel, Clock (wall + sim), Daemon, Supervisor.
+Project-URL: Repository, https://github.com/MilkClouds/chrono-daemon
+Author: Suhwan Choi
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: anyio>=4
+Provides-Extra: zmq
+Requires-Dist: msgspec>=0.18; extra == 'zmq'
+Requires-Dist: pyzmq>=26; extra == 'zmq'
+Description-Content-Type: text/markdown
+
+# chrono-daemon
+
+[![CI](https://github.com/MilkClouds/chrono-daemon/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/MilkClouds/chrono-daemon/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/chrono-daemon.svg)](https://pypi.org/project/chrono-daemon/)
+![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)
+![License: MIT](https://img.shields.io/badge/license-MIT-green)
+
+chrono-daemon is a small Python library for long-running async components whose time
+can be replayed deterministically. It wraps
+[anyio](https://anyio.readthedocs.io/) with four primitives:
+
+- `Channel[T]`: typed single-producer / single-consumer queues.
+- `Clock`: real time with `WallClock`, virtual time with `SimClock`.
+- `Daemon`: a lifecycle unit with `on_start`, `run`, and `on_stop`.
+- `Supervisor`: a structured-concurrency root for hosting daemons.
+
+The practical payoff is simple: production daemons sleep on `ctx.clock`; tests
+swap in `SimClock` and advance seconds of work without waiting for wall time.
+
+## Quick Example
+
+```python
+from chrono_daemon import Channel, Context, SimClock, Supervisor, daemon, open_channel
+
+@daemon
+async def producer(ctx: Context, out: Channel[int]) -> None:
+    for i in range(10):
+        await ctx.clock.sleep(0.1)
+        await out.send.send(i)
+    await out.send.aclose()
+
+@daemon
+async def consumer(ctx: Context, src: Channel[int]) -> None:
+    async for item in src.recv:
+        ctx.logger.info("got %d", item)
+
+async def main() -> None:
+    ch: Channel[int] = open_channel(maxsize=4)
+    clock = SimClock()
+    async with Supervisor(clock=clock) as sup:
+        sup.add(producer(ch))
+        sup.add(consumer(ch))
+        await clock.advance(1.5)  # replay 1.5 s of work immediately
+```
+
+## Why Use It
+
+- Time-dependent async code is testable without sleeps, polling, or fake
+  task schedulers.
+- Wiring is explicit. Every edge is a named SPSC channel, so ownership and
+  backpressure stay visible.
+- Lifecycle behavior is structured. Daemons get startup, shutdown, logging,
+  cancellation, and error policy in one place.
+- The core runtime is small: pure Python, `anyio` underneath, and no
+  runtime dependency beyond `anyio`.
+
+## Core API
+
+| | What it is |
+|---|---|
+| **`Channel[T]`** | typed bounded SPSC queue, the only inter-daemon communication primitive |
+| **`Clock`** | `WallClock` (real time) or `SimClock` (deterministic, burst `advance(dt)` / `advance_to(t)`) |
+| **`Daemon`** | long-running async unit; `on_start` / `run` / `on_stop` hooks. Use a subclass or the `@daemon` decorator |
+| **`Supervisor`** | `async with Supervisor(...)` structured-concurrency root; hosts daemons, dispatches errors (`shutdown` / `restart` / `ignore`) |
+
+See [`docs/concepts.md`](docs/concepts.md) for details.
+
+## Scope
+
+chrono-daemon is for in-process async systems where explicit wiring and deterministic
+time matter: evaluation loops, agent pipelines, robotics-style control mocks,
+and testable service internals.
+
+It is intentionally not a topic broker, service registry, RPC framework,
+parameter server, CLI launcher, network runtime, or continuous-time numerical
+simulator.
+
+## Install / dev
+
+```bash
+uv sync --dev --extra zmq
+make check        # ruff + pyrefly
+make test         # pytest on asyncio + trio
+make all          # format + check + test
+```
+
+Python 3.11+. Only runtime dependency is `anyio>=4`; `--extra zmq` installs
+the optional transport dependencies needed for the full test suite.
+Remote ZMQ channels are optional:
+
+```bash
+pip install "chrono-daemon[zmq]"
+```
+
+## Where to look next
+
+- [`docs/concepts.md`](docs/concepts.md): what each primitive is and the
+  invariants the test suite pins.
+- [`docs/adr/`](docs/adr/): why each decision looks the way it does
+  (Topic-less, on-error-shutdown by default, anyio-only).
+- [`docs/recipes.md`](docs/recipes.md): patterns kept off the core
+  surface but importable under `chrono_daemon.recipes.*`, grouped as routing,
+  coordination, state, buffering, and hosting helpers under
+  `src/chrono_daemon/recipes/`.
+- [`examples/`](examples/): runnable System 2/1/0 demos and notes.
+
+## Status
+
+Early. In-process channels are the default and keep zero runtime dependencies
+beyond `anyio`. ZMQ remote channels are available as an optional extra
+(`chrono-daemon[zmq]`) for asyncio-backed deployments.

chrono_daemon-0.1.0/README.md

@@ -0,0 +1,111 @@
+# chrono-daemon
+
+[![CI](https://github.com/MilkClouds/chrono-daemon/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/MilkClouds/chrono-daemon/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/chrono-daemon.svg)](https://pypi.org/project/chrono-daemon/)
+![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)
+![License: MIT](https://img.shields.io/badge/license-MIT-green)
+
+chrono-daemon is a small Python library for long-running async components whose time
+can be replayed deterministically. It wraps
+[anyio](https://anyio.readthedocs.io/) with four primitives:
+
+- `Channel[T]`: typed single-producer / single-consumer queues.
+- `Clock`: real time with `WallClock`, virtual time with `SimClock`.
+- `Daemon`: a lifecycle unit with `on_start`, `run`, and `on_stop`.
+- `Supervisor`: a structured-concurrency root for hosting daemons.
+
+The practical payoff is simple: production daemons sleep on `ctx.clock`; tests
+swap in `SimClock` and advance seconds of work without waiting for wall time.
+
+## Quick Example
+
+```python
+from chrono_daemon import Channel, Context, SimClock, Supervisor, daemon, open_channel
+
+@daemon
+async def producer(ctx: Context, out: Channel[int]) -> None:
+    for i in range(10):
+        await ctx.clock.sleep(0.1)
+        await out.send.send(i)
+    await out.send.aclose()
+
+@daemon
+async def consumer(ctx: Context, src: Channel[int]) -> None:
+    async for item in src.recv:
+        ctx.logger.info("got %d", item)
+
+async def main() -> None:
+    ch: Channel[int] = open_channel(maxsize=4)
+    clock = SimClock()
+    async with Supervisor(clock=clock) as sup:
+        sup.add(producer(ch))
+        sup.add(consumer(ch))
+        await clock.advance(1.5)  # replay 1.5 s of work immediately
+```
+
+## Why Use It
+
+- Time-dependent async code is testable without sleeps, polling, or fake
+  task schedulers.
+- Wiring is explicit. Every edge is a named SPSC channel, so ownership and
+  backpressure stay visible.
+- Lifecycle behavior is structured. Daemons get startup, shutdown, logging,
+  cancellation, and error policy in one place.
+- The core runtime is small: pure Python, `anyio` underneath, and no
+  runtime dependency beyond `anyio`.
+
+## Core API
+
+| | What it is |
+|---|---|
+| **`Channel[T]`** | typed bounded SPSC queue, the only inter-daemon communication primitive |
+| **`Clock`** | `WallClock` (real time) or `SimClock` (deterministic, burst `advance(dt)` / `advance_to(t)`) |
+| **`Daemon`** | long-running async unit; `on_start` / `run` / `on_stop` hooks. Use a subclass or the `@daemon` decorator |
+| **`Supervisor`** | `async with Supervisor(...)` structured-concurrency root; hosts daemons, dispatches errors (`shutdown` / `restart` / `ignore`) |
+
+See [`docs/concepts.md`](docs/concepts.md) for details.
+
+## Scope
+
+chrono-daemon is for in-process async systems where explicit wiring and deterministic
+time matter: evaluation loops, agent pipelines, robotics-style control mocks,
+and testable service internals.
+
+It is intentionally not a topic broker, service registry, RPC framework,
+parameter server, CLI launcher, network runtime, or continuous-time numerical
+simulator.
+
+## Install / dev
+
+```bash
+uv sync --dev --extra zmq
+make check        # ruff + pyrefly
+make test         # pytest on asyncio + trio
+make all          # format + check + test
+```
+
+Python 3.11+. Only runtime dependency is `anyio>=4`; `--extra zmq` installs
+the optional transport dependencies needed for the full test suite.
+Remote ZMQ channels are optional:
+
+```bash
+pip install "chrono-daemon[zmq]"
+```
+
+## Where to look next
+
+- [`docs/concepts.md`](docs/concepts.md): what each primitive is and the
+  invariants the test suite pins.
+- [`docs/adr/`](docs/adr/): why each decision looks the way it does
+  (Topic-less, on-error-shutdown by default, anyio-only).
+- [`docs/recipes.md`](docs/recipes.md): patterns kept off the core
+  surface but importable under `chrono_daemon.recipes.*`, grouped as routing,
+  coordination, state, buffering, and hosting helpers under
+  `src/chrono_daemon/recipes/`.
+- [`examples/`](examples/): runnable System 2/1/0 demos and notes.
+
+## Status
+
+Early. In-process channels are the default and keep zero runtime dependencies
+beyond `anyio`. ZMQ remote channels are available as an optional extra
+(`chrono-daemon[zmq]`) for asyncio-backed deployments.

chrono_daemon-0.1.0/docs/README.md

@@ -0,0 +1,30 @@
+# chrono-daemon docs
+
+This directory holds chrono-daemon's design and usage docs.
+
+## Layout
+
+- `concepts.md`: the four primitives (`Channel`, `Clock`, `Daemon`,
+  `Supervisor`), how they compose, and which invariants hold.
+- `adr/`: Architecture Decision Records. Each ADR is a frozen-in-time
+  statement of a load-bearing decision. New ADRs are added rather than
+  editing old ones; superseded ADRs link forward.
+- `recipes.md`: the user-facing index for `chrono_daemon.recipes`, grouped as
+  routing, coordination, state, buffering, and hosting helpers. Recipes are
+  importable but carry weaker stability guarantees than the core surface.
+- Optional transport adapters live in `src/chrono_daemon/transports/`. The first
+  one is `chrono_daemon.transports.zmq`, covered by `concepts.md` and ADR 0011.
+- `archive/`: long-form proposal notes preserved for design history, not as
+  the primary user documentation.
+
+## When to add what
+
+- A user-facing API change → update `concepts.md` and (if a tradeoff was
+  involved) a new ADR.
+- A "let's not do X" decision → ADR.
+- "How do I X" question that recurs → recipe.
+
+## When not to write docs here
+
+- Editing rules for agents belong outside the user-facing docs.
+- Per-PR justifications belong in the PR description.

chrono_daemon-0.1.0/docs/adr/0001-channel-is-the-sole-comm-primitive.md

@@ -0,0 +1,74 @@
+# ADR 0001: Channel is the sole communication primitive
+
+Status: Accepted (2026-05-18); superseded in part by ADR 0010
+
+Note: this ADR chose `Channel` as the only core communication primitive.
+ADR 0010 later changed the endpoint ownership rule from MPMC sharing to
+single-owner endpoints.
+
+## Context
+
+ROS-style frameworks expose pub/sub `Topic`, point-to-point queues, services,
+parameters, and broadcast events as distinct primitives. Each adds API
+surface, QoS knobs, and edge cases, most notably the *slow-consumer policy*
+problem: when a topic has N subscribers and one is slow, the publisher has to
+choose between blocking everyone, dropping for everyone, or dropping
+per-subscriber, and that choice has to live somewhere in the configuration
+matrix. ROS2's QoS profile sprawl is the load-bearing evidence that this is
+not a small cost.
+
+The target workloads for chrono-daemon, including robotics control loops, ML eval
+harnesses, and agent orchestration, are dominated by **statically wired** dataflow: the
+producer and the consumer of any given message are known at supervisor
+construction. Where dynamic subscription happens at all (log taps,
+visualizers), it is rare enough that handling it as an explicit, in-code
+fanout rather than a runtime-discovered subscription is acceptable.
+
+A 1:N broadcast can always be expressed as N 1:1 channels plus a fanout
+daemon. The reverse direction, taking a Topic and recovering "exactly one
+consumer gets each message", requires fighting the primitive.
+
+## Decision
+
+`Channel[T]` is the sole communication primitive in chrono_daemon. It is a typed,
+bounded queue with two endpoints, `send` and `recv`. As originally accepted,
+this ADR allowed multiple producers and consumers to share endpoints. ADR 0010
+supersedes that part: core channels now use single-owner endpoints and raise
+`ChannelInUse` on concurrent blocking endpoint sharing. Closing the send side
+propagates `EndOfStream` to receivers after the buffer drains.
+
+There is no `Topic`, no broadcast primitive, no service/RPC primitive, no
+parameter system, no discovery on the core surface. Users that need 1:N
+broadcast import `chrono_daemon.recipes.fanout.tee`. Recipes live under a
+sibling namespace (`chrono_daemon.recipes`) with weaker stability guarantees
+than the core (see `docs/recipes.md`), so they're available without
+copy-paste but are signaled as best-effort rather than part of the
+load-bearing API.
+
+## Consequences
+
++ One API to learn; static type checking on a single `Channel[T]`.
++ Backpressure has one meaning: `send` blocks while the receiver is slow.
+  No slow-consumer policy matrix, no QoS profile to negotiate.
++ Replay determinism is straightforward. There is no multi-subscriber
+  ordering ambiguity to specify.
++ Wiring is visible in code (every channel is a named local variable), so a
+  reader can statically trace dataflow.
+- 1:N broadcast costs the user a one-line `from chrono_daemon.recipes.fanout
+  import tee` plus the wiring. For workloads with pervasive broadcast
+  (e.g. a single `on_tick` driving multiple inference loops), the wiring
+  is still explicit, just import-able.
+- Migration from ROS code that relies on runtime subscriber discovery is
+  not a mechanical port. Every dynamic subscription has to become an
+  explicit channel handed in at construction.
+- Lifecycle-event streams that ROS users would express as a topic
+  ("session created/destroyed broadcasts") have to be modeled as either
+  N pre-allocated channels or a single channel with the `tee` recipe.
+
+## Related
+
+- ADR 0006 (transport adapter slot): `Channel` is a Protocol so multi-process
+  and network backends can be added later without reopening this decision.
+- `chrono_daemon.recipes.fanout.tee`: the canonical 1:N broadcast helper.
+- `chrono_daemon.recipes.batcher`: shows how request/response is built from
+  channels alone (no service primitive needed).

chrono_daemon-0.1.0/docs/adr/0002-wall-and-sim-clocks-as-pluggable-protocol.md

@@ -0,0 +1,74 @@
+# ADR 0002: Wall and Sim clocks as a pluggable Clock protocol
+
+Status: Accepted (2026-05-18)
+
+## Context
+
+The library's distinguishing capability vs. dora-rs, HORUS, Apollo CyberRT,
+and any "ROS for Python" attempt is **deterministic burst-step replay**: a
+driver task should be able to advance an entire scenario's worth of time in
+a single call (`await clock.advance(10.0)`) and observe daemons fire their
+sleeps and timers in exactly the order and at exactly the virtual instants
+they would have at wall-clock speed.
+
+`anyio` provides `current_time()` and `sleep()` as monotonic, backend-agnostic
+primitives, but does not provide a controllable virtual clock. trio's
+`MockClock` exists but is trio-specific. asyncio has nothing comparable.
+
+If daemon code is free to call `anyio.sleep` directly, no virtual clock can
+intercept it. Determinism would then depend on every daemon author
+remembering to use a `Clock` object. a passive convention is not strong
+enough.
+
+## Decision
+
+Time is reached through a `Clock` protocol with four methods: `now() -> float`,
+`async sleep(seconds)`, `async wait_until(deadline)`, and
+`every(period) -> AsyncIterator[float]`. Two
+implementations are provided:
+
+- `WallClock` uses `time.monotonic()` for `now()` and delegates sleeps to
+  `anyio.sleep`.
+- `SimClock` keeps an internal heap of `(deadline, sequence, anyio.Event)`
+  tuples. `sleep` enqueues; `advance(dt)` walks the heap in deadline order,
+  setting each event and yielding to let the woken task register a
+  follow-up sleep before the next iteration looks at the heap.
+
+`Context` exposes the active clock as `ctx.clock`. The CLAUDE.md editing rule
+"daemons must use `ctx.clock.sleep`, never `anyio.sleep`" is the convention
+that makes the interception complete; it is enforced socially, not by code.
+
+`SimClock.advance_to` performs a configurable `settle_rounds` checkpoint
+budget between successive wakes. The default is 8. This is empirically
+required on the trio backend, which does not necessarily resume a woken
+task on a single fairness round. anyio does not expose a backend-agnostic
+"run until all tasks are idle" primitive, so the budget is explicit rather
+than inferred.
+
+## Consequences
+
++ Deterministic burst-step replay is a first-class capability, not a
+  research-mode toggle.
++ Production daemons swap `SimClock` for `WallClock` with no code change.
++ Restart backoff, periodic timers, and any "wait until X seconds elapsed"
+  pattern all become deterministic under simulation, because they all go
+  through `Clock.sleep`.
+- The "always use `ctx.clock`" rule is a discipline, not a constraint
+  enforced by the type system. A daemon that imports `anyio.sleep` directly
+  silently breaks `SimClock`. The test suite has integration tests that would
+  detect it for in-tree code; user code is on the honor system.
+- `settle_rounds` is still a scheduler-settlement budget, not a proof of
+  global quiescence. Raising or lowering it changes how much downstream task
+  chaining one `advance_to()` call will absorb before finalizing.
+- Backend-agnostic deterministic primitives are an ongoing area of churn
+  in the anyio ecosystem; if a future anyio version ships an equivalent,
+  `SimClock` will likely be re-implemented on top of it rather than
+  remaining a hand-rolled heap.
+
+## Related
+
+- ADR 0008 (sim-aware logging) extends this by making `Context.logger`
+  carry sim-time on records, so burst-replay log output is interpretable.
+- `tests/test_clock.py::test_simclock_burst_step_deterministic_order` is
+  the canary: if this test fails on either backend, the rest of the system
+  is unreliable.