From d5e500cf4d3c92edb2440eb2b78b69d5e8b8a2c3 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 09:58:01 -0800 Subject: [PATCH 1/3] chore(quest): claim quest/m0/clock-guard/README.md Quest-Claim: cea3cc28d9f992cf From ce5f7f7188f1b481e32fd4365882d888202d6517 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 09:58:45 -0800 Subject: [PATCH 2/3] docs(review): tests mock time instead of waiting on the real clock Restores the mocked-clock rule that #7761 moved out of reviewers' sight, and finishes quest/m0/clock-guard. Co-Authored-By: Claude Opus 5.5 --- REVIEW.md | 7 +++++ quest/m0/README.md | 1 - quest/m0/clock-guard/README.md | 40 ----------------------------- quest/m1/mock-clock-tests/README.md | 4 +-- 4 files changed, 9 insertions(+), 43 deletions(-) delete mode 100644 quest/m0/clock-guard/README.md diff --git a/REVIEW.md b/REVIEW.md index a8347f002a6..d3624058cb2 100644 --- a/REVIEW.md +++ b/REVIEW.md @@ -27,6 +27,13 @@ Assume a better approach exists until you have tried to find one: An approach finding names the alternative and why it holds up better long-term. "Rework or abandon this PR" is a valid finding when the case is strong. +# Tests + +Unit tests mock time instead of waiting on the real clock: a test that sleeps to let work settle, or waits out a timeout to prove nothing happened, passes on a quiet machine and flakes under load. +Flag one in any language, even when the timer goes through `kio::clock` or `@moq/clock`, whose timers still wait in real time until the test installs a paused, simulated, or `Manual` clock. +The fix is a mocked clock or an awaited event, never a shorter or longer real wait, and the same fix lands in every language's sibling test. +The runtime guards fail Rust and bun tests only when a timer fires on the host clock, so they miss Go and Python tests and any wait that bypasses those clocks; and `host_time()` or `hostTime()` opts a test out, which belongs only where it drives real sockets, devices, or processes. + # Not findings Each of these has been raised and refuted repeatedly here; the rules in `AGENTS.md` already decide them: diff --git a/quest/m0/README.md b/quest/m0/README.md index 929667880e5..ac0a83b835c 100644 --- a/quest/m0/README.md +++ b/quest/m0/README.md @@ -36,5 +36,4 @@ edge, which embeds moq-relay; it moved there on 2026-09-28. - [Bun-spawning test recipes install the JS workspace](/quest/m0/recipe-js-install.md) - `bare-fin`, `max-age`, `stream-limits`, `relay-fill`, and `receive-credit` pass in a fresh checkout - [CI cost and latency](/quest/m0/ci/README.md) - cloud CI runs only in GitHub's merge queue, one tested entry at a time, expensive checks run nightly and gate `release`, caches move to R2, and runners are chosen last - [More tests under load](/quest/m0/test-flakes-2/README.md) - load-only and queue failures, one quest per flake, fixed at the cause, since each one drops a queued PR -- [Tests can't wait on the real clock](/quest/m0/clock-guard/README.md) - a test whose real-clock timer fires fails every run, in JS and, if the spike holds, Rust - [Agent build output can't fill the desktop's disk](/quest/m0/agent-disk-budget.md) - finished agent checkouts reclaim their mbx targets automatically, so parallel agent builds stop filling the root disk diff --git a/quest/m0/clock-guard/README.md b/quest/m0/clock-guard/README.md deleted file mode 100644 index 8c3121f0381..00000000000 --- a/quest/m0/clock-guard/README.md +++ /dev/null @@ -1,40 +0,0 @@ -# [M] Tests can't wait on the real clock - -## Goal - -A new test that waits on the real clock fails every run instead of flaking -1 in 20 under load. Today's lints ban how a timer is spelled, not the clock -it runs on: `clippy.toml` and biome send every timer to `kio::clock` or -`@moq/clock`, whose `sleep`/`timeout` still wait in real time unless the -test installs a paused, simulated, or `Manual` clock. So a test passes every -lint and still proves "nothing happened" by waiting 200 ms of wall time, -which is how the `copy_fill` `idle()` flake landed -([moq-dev/moq#7845](https://github.com/moq-dev/moq/pull/7845)) three days -after the lint. - -The tests already waiting in real time are burned down in m1's -[Tests run on a mocked clock](/quest/m1/mock-clock-tests/README.md). - -## Plan - -Decided 2026-11-06 (maintainer, /quest-complete, from an audit of every -test's clock): - -- ✅ **JS fails a test when a real-clock timer fires**, with a scoped - opt-out, plus a `REVIEW.md` rule and a biome deny on the `Bun` global. Not - chosen: a grep check over changed lines (misses shared helpers); a review - rule alone (reviewers flagged #4039, #3641, #1717, and #7845, and the - waits landed anyway). -- ✅ **Rust spikes the same guard**, falling back to a grep check if the - spike fails. Not chosen: a grep check only; JS only for now. -- ✅ m0 for the guards, since each real-time wait is a future merge-queue - flake; the burn-down is m1. - -This README's own work: restore the rule to `REVIEW.md`, for every language. -"Unit tests mock time instead of depending on wall-clock timing or sleeps" -sat in root `AGENTS.md` from #4286 until -[moq-dev/moq#7761](https://github.com/moq-dev/moq/pull/7761) moved it into -`quest context`, where online reviewers no longer see it; today only -`rs/AGENTS.md` and `rs/moq-net/AGENTS.md` say anything. The rule should say -what a fix looks like: a mocked clock or an awaited event, never a shorter -or longer real wait, and the same fix in every language's sibling test. diff --git a/quest/m1/mock-clock-tests/README.md b/quest/m1/mock-clock-tests/README.md index fec17ff85cf..4bcee02b9c3 100644 --- a/quest/m1/mock-clock-tests/README.md +++ b/quest/m1/mock-clock-tests/README.md @@ -18,8 +18,8 @@ test's clock): assertions.** Not chosen: only the first two; also the ~530 tests that only wait for progress under a timeout, which flake little and would cost a much larger migration. -- ✅ m1, while the [guards](/quest/m0/clock-guard/README.md) that stop new - ones are m0. +- ✅ m1, while the guards that stop new ones (the runtime guards and the + `REVIEW.md` rule) landed in m0. Rules every child keeps: From c88fdbcdaac2e75a19255f884802c31dad6130c7 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 11:10:22 -0800 Subject: [PATCH 3/3] docs(review): cover elapsed-time budgets, the real-I/O exception, and host_time's process scope Co-Authored-By: Claude Opus 5.5 --- REVIEW.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/REVIEW.md b/REVIEW.md index d3624058cb2..5673fe1078d 100644 --- a/REVIEW.md +++ b/REVIEW.md @@ -29,10 +29,11 @@ An approach finding names the alternative and why it holds up better long-term. # Tests -Unit tests mock time instead of waiting on the real clock: a test that sleeps to let work settle, or waits out a timeout to prove nothing happened, passes on a quiet machine and flakes under load. +Unit tests mock time instead of depending on the real clock: a test that sleeps to let work settle, waits out a timeout to prove nothing happened, or asserts that an operation finished within a real-time budget passes on a quiet machine and flakes under load. Flag one in any language, even when the timer goes through `kio::clock` or `@moq/clock`, whose timers still wait in real time until the test installs a paused, simulated, or `Manual` clock. -The fix is a mocked clock or an awaited event, never a shorter or longer real wait, and the same fix lands in every language's sibling test. -The runtime guards fail Rust and bun tests only when a timer fires on the host clock, so they miss Go and Python tests and any wait that bypasses those clocks; and `host_time()` or `hostTime()` opts a test out, which belongs only where it drives real sockets, devices, or processes. +The fix is a mocked clock or an awaited event, never a shorter or longer real wait or a looser budget, and the same fix lands in every language's sibling test. +The exception is a test that drives real sockets, devices, or processes, which may wait on the real clock and opts out with `host_time()` or `hostTime()`; that opt-out belongs nowhere else. +The runtime guards fail Rust and bun tests only when a timer fires on the host clock, so they miss Go and Python tests, elapsed-time assertions, and any wait that bypasses those clocks; and Rust's `host_time()` lasts for the whole process, so it hides other tests' waits outside nextest's one-test-per-process runs. # Not findings