workflow: bootstrap the run from run_started

[fantix]

Third of three, and the actual fix. Stacked on #283.

The bug

runtime.py opened workflow_handler with workflow_run = await world.runs_get(run_id). Since start() does not order its run_created write against the queue push, a delivery can arrive before the run row exists — so that read 404s. The queue was not set to redeliver, due to added latency.

Field evidence from the e2e Vercel lane: the 404 lands ~460ms after start(), runtime-logs record exactly 1 request for the run, and the driver waits out its 60s timeout. Roughly one arbitrary run per suite, on a different fixture each time — which reads as flakiness and is not. Three observed runs: two failed on sleepingWorkflow / promiseAllWorkflow, one passed because run_created happened to win.

The fix

Write run_started first instead of reading. It transitions the run to running and returns the run entity, so the read was a round-trip we never needed — and on a run whose row has not landed, it is the write that creates it from the runInput the message carried. This is what the TypeScript runtime does; the run row is a cache, not a precondition.

The creating client's specVersion is stamped on the event so a run this path creates is not relabelled to our SPEC_VERSION_CURRENT (2).

Cross-environment guard

Resilient start creates the run under our tenant, so a message whose run was created in another environment would fork it: two copies of one run id, the creator's pending forever and ours running, with every cross-tenant queue ack failing to find its message. refuse_cross_environment_delivery compares the creator's environment (from runInput) against our own and discards the delivery before the run_started write — refusing after it would be too late. It skips whenever either side is unknown, so the local world and older clients are unaffected.

Without this, the fix would trade a loud 404 for a much harder-to-diagnose fork.

Test plan

17 new tests. FakeWorld.runs_get raises outright, so any test that passes only because the handler read the run is failing by construction.

Mutation-checked: restoring the pre-read fails 15 of 17; dropping eventData, forcing SPEC_VERSION_CURRENT, skipping the guard, making the guard refuse on a match, widening the except, narrowing it to drop RunExpiredError, and dropping the cancelled check each fail at least one test.

Two notes on coverage:

• The body does not execute in these tests — the runtime re-imports the workflow's defining module by name and a test module is not importable that way. Setup is asserted up to the event-log load; end-to-end body execution is the e2e suite's job. The mutation run confirms this still pins every branch I changed.
• The cancelled early return looked redundant against the later status != "running" check until I mutation-tested it; it is load-bearing only for a run cancelled before it started, which has no startedAt. That case now has its own test.

Closes the resilient start: addTenWorkflow completes when run_created returns 500 conformance gap — the deterministic version of this same defect, currently carried as unsupported in the workbench app.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
vercel-py	Ready	Preview	Aug 12, 2026 2:34am