From 9d37a0a42eb101f6e07812f5c55137d2c7ed8c16 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 11:20:19 -0800 Subject: [PATCH 1/4] quest: Manual.drive waits for host I/O the work is blocked on Co-Authored-By: Claude Opus 5.5 --- quest/m1/mock-clock-tests/README.md | 1 + .../mock-clock-tests/manual-drive-host-io.md | 36 +++++++++++++++++++ 2 files changed, 37 insertions(+) create mode 100644 quest/m1/mock-clock-tests/manual-drive-host-io.md diff --git a/quest/m1/mock-clock-tests/README.md b/quest/m1/mock-clock-tests/README.md index fec17ff85cf..dab7fe990ad 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 host 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..19fd276139c --- /dev/null +++ b/quest/m1/mock-clock-tests/manual-drive-host-io.md @@ -0,0 +1,36 @@ +# [M] Manual.drive waits for host I/O the work is blocked on + +## Goal + +`Manual.drive` (`js/clock/src/manual.ts`) never fires a deadline while the +work it drives is still waiting on host I/O, such as a mocked stream read or +a dynamic `import()`, so time stops exactly at the deadline the work meets. +`js/net`'s `driveUntil` test helper is deleted and its callers use `drive`. + +## 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. Work parked on a later host task the clock doesn't count, such as a +mock transport's read resolving through a stream or a module import, looks +idle, so `drive` fires the next deadline early. Candidate fixes: + +- count that I/O: route the mock transport's deliveries and other test I/O + through a clock-counted task, so `#tasks` covers them; +- give `Manual` a way to hold time while named work is pending, released + when it settles. + +Prefer the one that needs no per-test annotation and keeps `drive`'s promise +that no wait outlives the call. Test it with work that reads from a mocked +stream and a dynamic `import()` before meeting a deadline, asserting the +clock stops at that deadline. Then replace every `driveUntil` call. + +Public API: may add to `@moq/clock`'s `Manual`, decided in the PR. 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 From a78d44a823304367292e31af8dbb41f2de2374dc Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 11:48:13 -0800 Subject: [PATCH 2/4] quest: scope Manual.drive to mocked I/O; predicate callers await their events Co-Authored-By: Claude Opus 5.5 --- quest/m1/mock-clock-tests/README.md | 2 +- .../mock-clock-tests/manual-drive-host-io.md | 44 +++++++++++-------- 2 files changed, 26 insertions(+), 20 deletions(-) diff --git a/quest/m1/mock-clock-tests/README.md b/quest/m1/mock-clock-tests/README.md index dab7fe990ad..13e284e05f8 100644 --- a/quest/m1/mock-clock-tests/README.md +++ b/quest/m1/mock-clock-tests/README.md @@ -45,4 +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 host 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 +- [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 index 19fd276139c..796ee8c8c2c 100644 --- a/quest/m1/mock-clock-tests/manual-drive-host-io.md +++ b/quest/m1/mock-clock-tests/manual-drive-host-io.md @@ -1,11 +1,12 @@ -# [M] Manual.drive waits for host I/O the work is blocked on +# [M] Manual.drive waits for mocked I/O the work is blocked on ## Goal `Manual.drive` (`js/clock/src/manual.ts`) never fires a deadline while the -work it drives is still waiting on host I/O, such as a mocked stream read or -a dynamic `import()`, so time stops exactly at the deadline the work meets. -`js/net`'s `driveUntil` test helper is deleted and its callers use `drive`. +work it drives is still waiting on a mocked transport's I/O, so time stops +exactly at the deadline the work meets. `js/net`'s `driveUntil` test helper +is deleted: a promise caller uses `drive`, and a predicate caller awaits +the event that flips its predicate. ## Plan @@ -15,21 +16,26 @@ Planned 2026-11-07 (maintainer, /quest-complete) from `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. Work parked on a later host task the clock doesn't count, such as a -mock transport's read resolving through a stream or a module import, looks -idle, so `drive` fires the next deadline early. Candidate fixes: - -- count that I/O: route the mock transport's deliveries and other test I/O - through a clock-counted task, so `#tasks` covers them; -- give `Manual` a way to hold time while named work is pending, released - when it settles. - -Prefer the one that needs no per-test annotation and keeps `drive`'s promise -that no wait outlives the call. Test it with work that reads from a mocked -stream and a dynamic `import()` before meeting a deadline, asserting the -clock stops at that deadline. Then replace every `driveUntil` call. - -Public API: may add to `@moq/clock`'s `Manual`, decided in the PR. Wire: none. +queued. Work parked on a mock transport's delivery, which resolves through a +stream on a later host task the clock doesn't count, looks idle, so `drive` +fires the next deadline early. Count that I/O: route the mock transport's +deliveries through a clock-counted task, so `#tasks` covers them with no +per-test annotation and `drive` keeps its promise that no wait outlives the +call. Test it with work that reads from a mocked stream before meeting a +deadline, asserting the clock stops at that deadline. + +Choices made while planning, open to review: + +- A predicate caller (most of them, such as the ~19 in + `js/net/src/connection/reload.test.ts`) awaits the signal or event its + predicate reads, per the epic's "await the event it means" rule. `drive` + stays promise-only rather than growing a predicate overload. +- 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 From b4323ce84fb40c75e222060eb4abb789cca53225 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 12:07:35 -0800 Subject: [PATCH 3/4] quest: Manual.drive holds only for queued deliveries and can't be starved Co-Authored-By: Claude Opus 5.5 --- .../mock-clock-tests/manual-drive-host-io.md | 24 ++++++++++++------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/quest/m1/mock-clock-tests/manual-drive-host-io.md b/quest/m1/mock-clock-tests/manual-drive-host-io.md index 796ee8c8c2c..a260e38938e 100644 --- a/quest/m1/mock-clock-tests/manual-drive-host-io.md +++ b/quest/m1/mock-clock-tests/manual-drive-host-io.md @@ -2,11 +2,12 @@ ## Goal -`Manual.drive` (`js/clock/src/manual.ts`) never fires a deadline while the -work it drives is still waiting on a mocked transport's I/O, so time stops -exactly at the deadline the work meets. `js/net`'s `driveUntil` test helper -is deleted: a promise caller uses `drive`, and a predicate caller awaits -the event that flips its predicate. +`Manual.drive` (`js/clock/src/manual.ts`) never fires a deadline while a +mocked transport delivery is already queued for the work it drives, so time +stops exactly at the deadline the work meets. A read with nothing in flight +still times out when its deadline comes. `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 @@ -22,14 +23,19 @@ fires the next deadline early. Count that I/O: route the mock transport's deliveries through a clock-counted task, so `#tasks` covers them with no per-test annotation and `drive` keeps its promise that no wait outlives the call. Test it with work that reads from a mocked stream before meeting a -deadline, asserting the clock stops at that deadline. +deadline, asserting the clock stops at that deadline. Deliveries must not +starve a deadline: hold time only for deliveries queued before the drain +that would fire it, not ones each delivery queues in turn, and add a test +with continuous background traffic whose deadline still fires. Choices made while planning, open to review: - A predicate caller (most of them, such as the ~19 in - `js/net/src/connection/reload.test.ts`) awaits the signal or event its - predicate reads, per the epic's "await the event it means" rule. `drive` - stays promise-only rather than growing a predicate overload. + `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 (such as + a give-up deadline) still fires. `drive` stays promise-only rather than + growing a predicate overload. - 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 From f2b3f42c60ddad4b61a05797d2a676cf888f5c8d Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 12:47:44 -0800 Subject: [PATCH 4/4] quest: Manual.drive's quest states outcomes and tests, not a mechanism Co-Authored-By: Claude Opus 5.5 --- .../mock-clock-tests/manual-drive-host-io.md | 44 +++++++++---------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/quest/m1/mock-clock-tests/manual-drive-host-io.md b/quest/m1/mock-clock-tests/manual-drive-host-io.md index a260e38938e..accf9711756 100644 --- a/quest/m1/mock-clock-tests/manual-drive-host-io.md +++ b/quest/m1/mock-clock-tests/manual-drive-host-io.md @@ -2,12 +2,11 @@ ## Goal -`Manual.drive` (`js/clock/src/manual.ts`) never fires a deadline while a -mocked transport delivery is already queued for the work it drives, so time -stops exactly at the deadline the work meets. A read with nothing in flight -still times out when its deadline comes. `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. +`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 @@ -17,26 +16,27 @@ Planned 2026-11-07 (maintainer, /quest-complete) from `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. Work parked on a mock transport's delivery, which resolves through a -stream on a later host task the clock doesn't count, looks idle, so `drive` -fires the next deadline early. Count that I/O: route the mock transport's -deliveries through a clock-counted task, so `#tasks` covers them with no -per-test annotation and `drive` keeps its promise that no wait outlives the -call. Test it with work that reads from a mocked stream before meeting a -deadline, asserting the clock stops at that deadline. Deliveries must not -starve a deadline: hold time only for deliveries queued before the drain -that would fire it, not ones each delivery queues in turn, and add a test -with continuous background traffic whose deadline still fires. - -Choices made while planning, open to review: +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 (such as - a give-up deadline) still fires. `drive` stays promise-only rather than - growing a predicate overload. -- A dynamic `import()` is out of scope. JavaScript exposes no "host queue + "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.