Scope correlation-ID event lookups to a run

[karthikscale3]

What

Correlation-ID event lookups (events.listByCorrelationId) now accept and send an optional runId.

• @workflow/world: optional runId on the params (additive — existing World implementations keep working unchanged).
• @workflow/world-vercel: sends runId as a query parameter when provided, and keeps filtering the returned page by run as a compatibility guard for backends that ignore it.
• @workflow/web: the run-details event view now passes the run it is already looking at through to the lookup (it previously only filtered results by it client-side).
• @workflow/world-local / @workflow/world-postgres: honor the new param.

Why

A correlation ID names a step, hook, or wait within its run — it isn't guaranteed unique across runs. Scoping the lookup to the run makes it precise and lets backends answer from the run's own event log instead of a cross-run search. This brings the 4.x line in step with 5.x, where runId is already required on this call (#3280) — kept optional here so it lands as a non-breaking patch.

Behavior

Optional everywhere: older backends ignore the param and the client-side run filter preserves today's results; no behavior change for any caller that doesn't pass runId.

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: a9587c2

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 20 packages

Name	Type
@workflow/world	Minor
@workflow/world-vercel	Patch
@workflow/world-local	Patch
@workflow/world-postgres	Patch
@workflow/web	Patch
@workflow/cli	Patch
@workflow/core	Patch
@workflow/vitest	Patch
@workflow/web-shared	Patch
@workflow/world-testing	Patch
@workflow/nitro	Patch
workflow	Patch
@workflow/builders	Patch
@workflow/next	Patch
@workflow/nuxt	Patch
@workflow/astro	Patch
@workflow/nest	Patch
@workflow/rollup	Patch
@workflow/sveltekit	Patch
@workflow/vite	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
example-nextjs-workflow-turbopack	Ready	Preview, v0	Aug 24, 2026 8:53pm
example-nextjs-workflow-webpack	Ready	Preview, v0	Aug 24, 2026 8:53pm
example-workflow	Ready	Preview, v0	Aug 24, 2026 8:53pm
workbench-astro-workflow	Ready	Preview, v0	Aug 24, 2026 8:53pm
workbench-express-workflow	Ready	Preview, v0	Aug 24, 2026 8:53pm
workbench-fastify-workflow	Ready	Preview, v0	Aug 24, 2026 8:53pm
workbench-hono-workflow	Ready	Preview, v0	Aug 24, 2026 8:53pm
workbench-nestjs-workflow	Ready	Preview, v0	Aug 24, 2026 8:53pm
workbench-nitro-workflow	Ready	Preview, v0	Aug 24, 2026 8:53pm
workbench-nuxt-workflow	Ready	Preview, v0	Aug 24, 2026 8:53pm
workbench-python-workflow	Error	v0	Aug 24, 2026 8:53pm
workbench-sveltekit-workflow	Ready	Preview, v0	Aug 24, 2026 8:53pm
workbench-tanstack-start-workflow	Ready	Preview, v0	Aug 24, 2026 8:53pm
workbench-vite-workflow	Ready	Preview, v0	Aug 24, 2026 8:53pm
workflow-docs	Ready	Preview, v0	Aug 24, 2026 8:53pm
workflow-swc-playground	Ready	Preview, v0	Aug 24, 2026 8:53pm
workflow-tarballs	Ready	Preview, v0	Aug 24, 2026 8:53pm
workflow-web	Ready	Preview, v0	Aug 24, 2026 8:53pm

[github-actions]

🧪 E2E Test Results

❌ Some tests failed

Summary

	Passed	Failed	Skipped	Total
✅ ▲ Vercel Production	1099	0	78	1177
✅ 💻 Local Development	1198	0	86	1284
✅ 📦 Local Production	1198	0	86	1284
✅ 🐘 Local Postgres	1198	0	86	1284
✅ 🪟 Windows	107	0	0	107
❌ 🌍 Community Worlds	82	106	9	197
✅ 📋 Other	606	0	36	642
Total	5488	106	381	5975

❌ Failed Tests

🌍 Community Worlds (106 failed)

redis (21 failed):

• hookWorkflow | wrun_01M0TRPYPB8TGWJ25PR3SRDEJ1
• hookWorkflow is not resumable via public webhook endpoint | wrun_01M0TRQ72BA0NP9BE1TX28ES9N
• parallelStepsThenWebhookWorkflow - no hook_conflict from same-tick replay race | wrun_01M0TRQG825W6A4R3YETNDNCC3
• sleepingWorkflow | wrun_01M0TRRFB35J67M5AFCBSRK1NW
• outputStreamWorkflow negative startIndex (reads from end)
• outputStreamWorkflow - getTailIndex and getStreamChunks getTailIndex returns correct index after stream completes
• outputStreamWorkflow - getTailIndex and getStreamChunks getTailIndex returns -1 before any chunks are written
• outputStreamWorkflow - getTailIndex and getStreamChunks getStreamChunks returns same content as reading the stream
• error handling serialization failures step-argument serialization failure is catchable in workflow code
• error handling serialization failures uncaught step-argument serialization failure fails the run as USER_ERROR without redelivery retries
• concurrent hook token conflict - two workflows cannot use the same hook token simultaneously | wrun_01M0TS0J3HCZ7R4GX7ES7C0FV6
• hookGetConflictWorkflow - awaiting hook.getConflict() registers hook without payload | wrun_01M0TS0YB8ERF7YXWKRQ7SYC0N
• hookGetConflictThenStepParallelWorkflow - hook.getConflict() continuation step runs alongside other steps | wrun_01M0TS15F0GT4MHTCX3WTB57V5
• hookGetConflictWorkflow - hook.getConflict() resolves with the conflicting run when token is already registered | wrun_01M0TS1KZJ09EVT2XE29S46MTX
• hookClaimOnlyMutexWorkflow - hook works as a pure run mutex without payload data | wrun_01M0TS2DR80CJD5DA60Y0EPGS5
• hookAdoptOwnerResultWorkflow - duplicate adopts the owner result via conflict.returnValue | wrun_01M0TS2HJ3X01DGMKQX6RKX1P8
• hookSignalOwnerWorkflow - duplicate forwards its payload to the owner via resumeHook | wrun_01M0TS2P8YHAA31JS0H3EA7WT4
• hookSupersedeOwnerWorkflow - duplicate cancels the owner and claims the released token | wrun_01M0TS2VCJJ8G5P2M1XP1W6YCQ
• resume-or-start route pattern - resumeHook retried after start() reaches the new run | wrun_01M0TS336P4SRXCY7KYH9FPKAP
• pages router sleepingWorkflow via pages router
• resilient start: addTenWorkflow completes when run_created returns 500 | wrun_01M0TS8JGP1DR0PSX5FGJYSZ26

turso (85 failed):

• addTenWorkflow | wrun_01M0TRP00SRJXFV3KJ29TMBF7Z
• addTenWorkflow | wrun_01M0TRP00SRJXFV3KJ29TMBF7Z
• deploymentId: 'latest' is a no-op in non-Vercel worlds
• wellKnownAgentWorkflow (.well-known/agent) | wrun_01M0TRPMHZE5ATA0N0Y4EXJERA
• should work with react rendering in step
• promiseAllWorkflow | wrun_01M0TRP7S1AHN7NK22EMYBE0C6
• promiseRaceWorkflow | wrun_01M0TRPD8XKQDSB83DX08QEGFE
• promiseAnyWorkflow | wrun_01M0TRPFH4W079GJ4A0ZTSE05Y
• importedStepOnlyWorkflow | wrun_01M0TRQ15YXJFSTDYKTQR8NBQD
• readableStreamWorkflow | wrun_01M0TRPHQM5XZGJ222N3P1ECZJ
• hookWorkflow | wrun_01M0TRPYPB8TGWJ25PR3SRDEJ1
• hookWorkflow is not resumable via public webhook endpoint | wrun_01M0TRQ72BA0NP9BE1TX28ES9N
• webhookWorkflow | wrun_01M0TRQB9YQQ0KN657HH6B67HH
• parallelStepsThenWebhookWorkflow - no hook_conflict from same-tick replay race | wrun_01M0TRQG825W6A4R3YETNDNCC3
• sleepingWorkflow | wrun_01M0TRRFB35J67M5AFCBSRK1NW
• parallelSleepWorkflow | wrun_01M0TRRYJC9CN53ZCWHDDDHQJ7
• sleepWinsRaceWorkflow | wrun_01M0TRS32N84PG42PFMGXS1S9B
• stepWinsRaceWorkflow | wrun_01M0TRS6CWNK0H3BE70194BAVY
• nullByteWorkflow | wrun_01M0TRS9KX70BC4D63ZXYS9E7S
• workflowAndStepMetadataWorkflow | wrun_01M0TRSBRFH1Q5GEYY0PAG4RK8
• outputStreamWorkflow no startIndex (reads all chunks)
• outputStreamWorkflow positive startIndex (skips first chunk)
• outputStreamWorkflow negative startIndex (reads from end)
• outputStreamWorkflow - getTailIndex and getStreamChunks getTailIndex returns correct index after stream completes
• outputStreamWorkflow - getTailIndex and getStreamChunks getTailIndex returns -1 before any chunks are written
• outputStreamWorkflow - getTailIndex and getStreamChunks getStreamChunks returns same content as reading the stream
• outputStreamInsideStepWorkflow - getWritable() called inside step functions | wrun_01M0TRVK45YRFYRX3YM5PWSD9X
• writableForwardedFromWorkflowWorkflow | wrun_01M0TRW0Y9ZDSGFWQYTVHQ56F8
• writableForwardedFromStepWorkflow | wrun_01M0TRW5KF60NM8DGKVP4V89AY
• fetchWorkflow | wrun_01M0TRW9862Q0WX5MR0Y473K4N
• promiseRaceStressTestWorkflow | wrun_01M0TRWCQJFGCNEFANYQ3S6H9H
• error handling error propagation workflow errors nested function calls preserve message and stack trace
• error handling error propagation workflow errors cross-file imports preserve message and stack trace
• error handling error propagation step errors basic step error preserves message and stack trace
• error handling error propagation step errors cross-file step error preserves message and function names in stack
• error handling retry behavior regular Error retries until success
• error handling retry behavior FatalError fails immediately without retries
• error handling retry behavior RetryableError respects custom retryAfter delay
• error handling retry behavior maxRetries=0 disables retries
• error handling catchability FatalError can be caught and detected with FatalError.is()
• error handling serialization failures step-argument serialization failure is catchable in workflow code
• error handling serialization failures uncaught step-argument serialization failure fails the run as USER_ERROR without redelivery retries
• error handling not registered WorkflowNotRegisteredError fails the run when workflow does not exist
• error handling not registered StepNotRegisteredError fails the step but workflow can catch it
• error handling not registered StepNotRegisteredError fails the run when not caught in workflow
• hookCleanupTestWorkflow - hook token reuse after workflow completion | wrun_01M0TS06VS42K1HA9F4YMT1KMD
• concurrent hook token conflict - two workflows cannot use the same hook token simultaneously | wrun_01M0TS0J3HCZ7R4GX7ES7C0FV6
• hookGetConflictWorkflow - awaiting hook.getConflict() registers hook without payload | wrun_01M0TS0YB8ERF7YXWKRQ7SYC0N
• 'hookGetConflictWithPriorStepWorkflow' - hook.getConflict() does not block step execution | wrun_01M0TS10RMFSTX3VB6YVPMPGQT
• 'hookGetConflictWithParallelStepWorkfl…' - hook.getConflict() does not block step execution | wrun_01M0TS130P7ANB4FG5PXD4Z8VJ
• hookGetConflictThenStepParallelWorkflow - hook.getConflict() continuation step runs alongside other steps | wrun_01M0TS15F0GT4MHTCX3WTB57V5
• hookGetConflictWorkflow - hook.getConflict() resolves with the conflicting run when token is already registered | wrun_01M0TS1KZJ09EVT2XE29S46MTX
• hookClaimOnlyMutexWorkflow - hook works as a pure run mutex without payload data | wrun_01M0TS2DR80CJD5DA60Y0EPGS5
• hookAdoptOwnerResultWorkflow - duplicate adopts the owner result via conflict.returnValue | wrun_01M0TS2HJ3X01DGMKQX6RKX1P8
• hookSignalOwnerWorkflow - duplicate forwards its payload to the owner via resumeHook | wrun_01M0TS2P8YHAA31JS0H3EA7WT4
• hookSupersedeOwnerWorkflow - duplicate cancels the owner and claims the released token | wrun_01M0TS2VCJJ8G5P2M1XP1W6YCQ
• resume-or-start route pattern - resumeHook retried after start() reaches the new run | wrun_01M0TS336P4SRXCY7KYH9FPKAP
• hookDisposeTestWorkflow - hook token reuse after explicit disposal while workflow still running | wrun_01M0TS39NK8AA6TBZB0XSW5Y0C
• stepFunctionPassingWorkflow - step function references can be passed as arguments (without closure vars) | wrun_01M0TS3RCB0WK90YDG3ZP5V1TR
• stepFunctionWithClosureWorkflow - step function with closure variables passed as argument | wrun_01M0TS419QSQ7BMNYK0F5C4K3F
• closureVariableWorkflow - nested step functions with closure variables | wrun_01M0TS46NWH4WZYC1RPDV9GTH9
• spawnWorkflowFromStepWorkflow - spawning a child workflow using start() inside a step | wrun_01M0TS48W86XKDQC6MV39JHNZC
• health check (queue-based) - workflow and step endpoints respond to health check messages
• health check (CLI) - workflow health command reports healthy endpoints
• pathsAliasWorkflow - TypeScript path aliases resolve correctly | wrun_01M0TS4Q0XPG792PXSQPFBAB5R
• Calculator.calculate - static workflow method using static step methods from another class | wrun_01M0TS4WJ7TN1PVCVV3BN377SP
• AllInOneService.processNumber - static workflow method using sibling static step methods | wrun_01M0TS533F8BBRWKZTDZCJ752X
• ChainableService.processWithThis - static step methods using this to reference the class | wrun_01M0TS59RN7HTQWHDFJDHVVD0Q
• thisSerializationWorkflow - step function invoked with .call() and .apply() | wrun_01M0TS5GB41Q6G783K37N20P3Y
• customSerializationWorkflow - custom class serialization with WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE | wrun_01M0TS5PY336RHSSQP2E68BPAE
• instanceMethodStepWorkflow - instance methods with "use step" directive | wrun_01M0TS60W8JBTZ7JG87K0FNY0W
• crossContextSerdeWorkflow - classes defined in step code are deserializable in workflow context | wrun_01M0TS6D2FJ92BSVCY3PHRPVNB
• stepFunctionAsStartArgWorkflow - step function reference passed as start() argument | wrun_01M0TS6N375AG2NQDMN1Y2CYC7
• cancelRun - cancelling a running workflow | wrun_01M0TS6VW8JH27HQYW2EG4VXAP
• cancelRun via CLI - cancelling a running workflow | wrun_01M0TS70RP99Y7EWRVQGJB5X71
• pages router addTenWorkflow via pages router
• pages router promiseAllWorkflow via pages router
• pages router sleepingWorkflow via pages router
• hookWithSleepWorkflow - hook payloads delivered correctly with concurrent sleep | wrun_01M0TS782QNPC2HM9KR1S374QE
• hookWithSleepFinalStepWorkflow - step only on final payload | wrun_01M0TS7MQBFY6N5WEFTHMCMMFG
• sleepInLoopWorkflow - sleep inside loop with steps actually delays each iteration | wrun_01M0TS7X8QKV78RTJXP92EETAQ
• sleepWithSequentialStepsWorkflow - sequential steps work with concurrent sleep (control) | wrun_01M0TS87GA1RD8G007QK8FCRP0
• importMetaUrlWorkflow - import.meta.url is available in step bundles | wrun_01M0TS8E7G2BBW3P8PY9Z9G95M
• metadataFromHelperWorkflow - getWorkflowMetadata/getStepMetadata work from module-level helper (#1577) | wrun_01M0TS8G9W5H50NNYRP2KVE0XF
• resilient start: addTenWorkflow completes when run_created returns 500 | wrun_01M0TS8JGP1DR0PSX5FGJYSZ26

Details by Category

✅ ▲ Vercel Production

App	Passed	Failed	Skipped
✅ astro	99	0	8
✅ example	99	0	8
✅ express	99	0	8
✅ fastify	99	0	8
✅ hono	99	0	8
✅ nextjs-turbopack	104	0	3
✅ nextjs-webpack	104	0	3
✅ nitro	99	0	8
✅ nuxt	99	0	8
✅ sveltekit	99	0	8
✅ vite	99	0	8

✅ 💻 Local Development

App	Passed	Failed	Skipped
✅ astro-stable	101	0	6
✅ express-stable	101	0	6
✅ fastify-stable	101	0	6
✅ hono-stable	101	0	6
✅ nextjs-turbopack-canary	88	0	19
✅ nextjs-turbopack-stable	107	0	0
✅ nextjs-webpack-canary	88	0	19
✅ nextjs-webpack-stable	107	0	0
✅ nitro-stable	101	0	6
✅ nuxt-stable	101	0	6
✅ sveltekit-stable	101	0	6
✅ vite-stable	101	0	6

✅ 📦 Local Production

App	Passed	Failed	Skipped
✅ astro-stable	101	0	6
✅ express-stable	101	0	6
✅ fastify-stable	101	0	6
✅ hono-stable	101	0	6
✅ nextjs-turbopack-canary	88	0	19
✅ nextjs-turbopack-stable	107	0	0
✅ nextjs-webpack-canary	88	0	19
✅ nextjs-webpack-stable	107	0	0
✅ nitro-stable	101	0	6
✅ nuxt-stable	101	0	6
✅ sveltekit-stable	101	0	6
✅ vite-stable	101	0	6

✅ 🐘 Local Postgres

App	Passed	Failed	Skipped
✅ astro-stable	101	0	6
✅ express-stable	101	0	6
✅ fastify-stable	101	0	6
✅ hono-stable	101	0	6
✅ nextjs-turbopack-canary	88	0	19
✅ nextjs-turbopack-stable	107	0	0
✅ nextjs-webpack-canary	88	0	19
✅ nextjs-webpack-stable	107	0	0
✅ nitro-stable	101	0	6
✅ nuxt-stable	101	0	6
✅ sveltekit-stable	101	0	6
✅ vite-stable	101	0	6

✅ 🪟 Windows

App	Passed	Failed	Skipped
✅ nextjs-turbopack	107	0	0

❌ 🌍 Community Worlds

App	Passed	Failed	Skipped
✅ mongodb-dev	4	0	3
✅ redis-dev	4	0	3
❌ redis	67	21	0
✅ turso-dev	4	0	3
❌ turso	3	85	0

✅ 📋 Other

App	Passed	Failed	Skipped
✅ e2e-local-dev-nest-stable	101	0	6
✅ e2e-local-dev-tanstack-start-stable	101	0	6
✅ e2e-local-postgres-nest-stable	101	0	6
✅ e2e-local-postgres-tanstack-start-stable	101	0	6
✅ e2e-local-prod-nest-stable	101	0	6
✅ e2e-local-prod-tanstack-start-stable	101	0	6

---

📋 View full workflow run