No worker-side executor double: async-job tests spin a real thread pool and sleep between polls

[Yaraslaut]

The gap

morph has executor doubles for the delivery order of continuations, but nothing that substitutes for the worker side of an async job. Every async-job test therefore runs a real thread pool and waits on wall-clock time.

What exists:

double	where	what it controls
DeterministicExecutor	examples/common/testkit/strand_interleaver.hpp, tests/test_support.hpp	the order in which queued continuations are delivered
StepExecutor	tests/test_support.hpp	stepping continuation delivery
InlineExecutor	tests/test_support.hpp	running a continuation inline

All of these sit on the callback side. None of them lets a test say "the background job has now run, and not before".

What it costs today

examples/ledger/tests/test_ledger_reports.cpp has to poll:

/// Polls @p model's `GetReportStatus` for @p jobId until it leaves `Pending`,
/// or until the hard iteration cap is reached.
/// ... the real `ThreadPoolExecutor` and sleeps between polls.
status = model.execute(ledger::GetReportStatus{.jobId = jobId});
if (status.status != ledger::ReportStatus::Pending) { break; }
std::this_thread::sleep_for(std::chrono::milliseconds(10));

Three properties follow, none of them good:

• Wall-clock cost on every run, paid whether or not anything is wrong.
• A flakiness budget: the iteration cap is a guess about how slow a machine may be. This repository has already been bitten by exactly that shape — morph#147 was a pumpUntil budget that was fine on CI runners and failed deterministically on a slower machine.
• Unobservable intermediate states. "Submitted, still Pending, worker has not run yet" cannot be asserted deterministically; the test can only sample and hope.

examples/ledger/tests/test_report_job_poller.cpp shows the same shape from the other side — REQUIRE_FALSE(pumpUntil([] { return false; }, 120ms)) to assert a non-event, which is 120 ms of sleeping per assertion.

What is wanted

An IExecutor that queues tasks and runs them only when told:

ManualExecutor worker;
// ... submit the job ...
CHECK(status == Pending);       // asserted, not sampled: the worker has not run
CHECK(worker.runOne());
CHECK(status == Done);          // no sleep, no cap, no flakiness budget

It should also pick up tasks posted by a task, so a chained job runs to completion rather than stranding its own continuation. Not thread-safe by design — a test reasoning about exact task ordering drives it from one thread.

This is roughly 30 lines. A version was written as part of #154 (now closed) and can be lifted from that branch; it does not depend on anything else in that PR.

Where it belongs

The testkit, not include/morph/. Per #129, background jobs live at the App/server layer, so it is the App layer's tests that need to drive a worker deterministically. examples/common/testkit/ alongside the existing doubles is the natural home; tests/test_support.hpp if a framework-level test wants it too.

Context

Split out of #129, which was closed on the architectural point that models should not know about the framework. This part survives that decision: moving background jobs to the App layer relocates the testing gap rather than closing it. Related: #160 (ledger's own background job, which is the concrete case).

[Yaraslaut]

Implemented in #222, with two corrections to this issue's framing that are worth recording rather than shipping around.

1. The double already existed; the gap was reachability, not semantics.

This issue's table lists morph::testing::StepExecutor (tests/test_support.hpp) among the doubles that "sit on the callback side", and concludes "none of them lets a test say 'the background job has now run, and not before'."

StepExecutor does exactly that already — post/runOne/runAll/pending, mutex-guarded, bounded runAll, picks up tasks posted by a running task. It is byte-for-byte the design #154's ManualExecutor describes. An IExecutor has no "callback side": what it drives is decided entirely by what it is plugged into, and plugged in as LedgerModel::_reportExecutor it is the worker-side double this issue asks for.

What was actually missing is an include path. tests/test_support.hpp is private to morph_tests' own translation units and is not reachable from examples/. That is why every ladder async-job test spins a real pool — not because the semantics had never been written.

So #222 mirrors it into examples/common/testkit/step_executor.hpp under the same name, following the duplication DeterministicExecutor already does from that same header, rather than introducing a differently-named ManualExecutor for the same class.

2. "Wall-clock cost on every run" is worth about 26 ms here, not seconds.

Measured on the ledger suite, interleaved runs of the two binaries, steady state:

before (5 cases): 1.28  1.29  1.29 s
after  (7 cases): 1.54  1.54  1.57 s

On the five cases common to both: 1.223 s → 1.197 s.

Roughly 2 s of sleep_for calls did disappear (an instrumented pollUntilSettled sleeps 7–15 times per call site). But those sleeps overlapped the worker's real work — a report job spends ~70–150 ms, mostly acquiring a pooled DataMapper — so only the last partial 10 ms slice per call site was ever wall-clock.

The other two costs this issue names are real and are what the change actually buys:

• Unobservable intermediate states — now assertable. Replacing _reportExecutor->post(task) with an inline call, so SubmitReport computes the entire report synchronously on the caller's thread, leaves the pre-change suite entirely green (44 assertions, 5 cases) and fails 20 assertions across 4 cases of the converted one.
• The flakiness budget — quantified and filed separately as The one surviving fixed-wall-clock poll (test_ledger_reports.cpp) should use a MORPH_LADDER_DEADLINE_MS-scaled deadline, not a hand-picked 100x10ms budget #223: the cap is a ~6.7x margin on an idle machine, not the "far inside the budget" its comment claimed.

3. Not everything was converted, on purpose.

One case keeps a real ThreadPoolExecutor: it is the only coverage of the default-constructed LedgerModel (the constructor the bridge registry uses) and the only one where the worker runs on a genuinely different thread with the caller's thread-local session context absent. A worker wrongly reaching for morph::session::current() would pass every converted case and fail only there. That case still carries the retry cap, which is what #223 is about.