diff --git a/quest/m1/mock-clock-tests/README.md b/quest/m1/mock-clock-tests/README.md index fec17ff85cf..13e284e05f8 100644 --- a/quest/m1/mock-clock-tests/README.md +++ b/quest/m1/mock-clock-tests/README.md @@ -45,3 +45,4 @@ before starting, since tests land and move. - [js/net tests run on a mocked clock](/quest/m1/mock-clock-tests/js-net.md) - about 120 js/net tests stop waiting on real time, through their shared helpers - [Other JS tests run on a mocked clock](/quest/m1/mock-clock-tests/js-rest.md) - hang's `settle(20)`, publish's fanout helpers, and the rest of JS - [moq-relay's mesh tests run on a mocked clock](/quest/m1/mock-clock-tests/rs-relay.md) - the relay's multi-relay quiet windows and settle sleeps +- [Manual.drive waits for mocked I/O the work is blocked on](/quest/m1/mock-clock-tests/manual-drive-host-io.md) - `drive` stops at the deadline the work meets, and `js/net`'s `driveUntil` workaround is deleted diff --git a/quest/m1/mock-clock-tests/manual-drive-host-io.md b/quest/m1/mock-clock-tests/manual-drive-host-io.md new file mode 100644 index 00000000000..accf9711756 --- /dev/null +++ b/quest/m1/mock-clock-tests/manual-drive-host-io.md @@ -0,0 +1,48 @@ +# [M] Manual.drive waits for mocked I/O the work is blocked on + +## Goal + +`Manual.drive` (`js/clock/src/manual.ts`) stops time exactly at the deadline +the driven work meets, even when the work first waits on a mocked transport +delivery. `js/net`'s `driveUntil` test helper is deleted: every caller +passes `drive` a promise, a predicate caller one that resolves on the event +its predicate reads. + +## Plan + +Planned 2026-11-07 (maintainer, /quest-complete) from +[moq-dev/moq#8165](https://github.com/moq-dev/moq/pull/8165), which adds +`driveUntil` to `js/net/src/mock.ts` as a workaround: it alternates +`yieldNow()` with 1 ms `advance` steps for up to ten mocked seconds. + +`drive` advances once a `drain()` (one host task) leaves no counted yield +queued, so work parked on a mock delivery that resolves on a later, +uncounted host task looks idle, and `drive` fires the next deadline early. + +Decided at the design checkpoint (maintainer, 2026-11-07): ✅ this quest +states outcomes and required tests, and the mechanism is chosen in its PR. +Not chosen: prescribing one here, which took three review rounds without +settling. Required tests: + +- a read whose delivery is queued resolves before the clock passes its + deadline, and the clock stops at the deadline the work then meets; +- a read with nothing in flight times out when its deadline comes; +- continuous background deliveries never starve a deadline. + +Also settled: + +- A predicate caller (most of them, such as the ~19 in + `js/net/src/connection/reload.test.ts`) passes `drive` a promise that + resolves on the signal or event its predicate reads, per the epic's + "await the event it means" rule, so a timer the event depends on still + fires. `drive` stays promise-only. +- A dynamic `import()` is out of scope: JavaScript exposes no "host queue + empty" signal, so a clock-side quiescence check would be a quiet window, + which the epic rules out. A test whose work imports a module loads it + before driving. + +Public API: none beyond `@moq/clock`'s test helpers, if any. Wire: none. + +## Required + +- [js/net tests run on a mocked clock](/quest/m1/mock-clock-tests/js-net.md) - adds the `driveUntil` callers this replaces