Skip to content

[core] Correct byte-stream framing capability cutoff (stable) - #2768

Merged
VaguelySerious merged 2 commits into
stablefrom
peter/framing-capability-cutoff
Jul 3, 2026
Merged

[core] Correct byte-stream framing capability cutoff (stable)#2768
VaguelySerious merged 2 commits into
stablefrom
peter/framing-capability-cutoff

Conversation

@VaguelySerious

Copy link
Copy Markdown
Member

Summary

Two fixes to the framedByteStreams capability gate introduced by the byte-stream framing backport (#2380, from #1853), ahead of the 4.6.0 stable release (#2426):

  1. Bump the cutoff from 4.5.0 to 4.6.0. Stable 4.5.0 was published ~2.5 hours before Backport #1853: [core] Add wire-level framing for byte streams #2380 merged, so published 4.5.0 has no framing code — it silently ignores the framing field on stream refs and pipes length-prefixed bytes straight to user code. With the old cutoff, a 4.6.0 producer targeting a 4.5.0 deployment (cross-deployment start(), hook resume into a 4.5.0-created run) would cause silent byte-stream corruption. This resolves the TODO(release) left in capabilities.ts by Backport #1853: [core] Add wire-level framing for byte streams #2380.

  2. Replace the plain minimum-version check with a semver range (>=4.6.0 <5.0.0-0 || >=5.0.0-beta.15, evaluated with includePrerelease). Every 5.0.0-beta.x compares above any 4.x version, but betas below 5.0.0-beta.15 (published 2026-04-08 through 2026-06-11) predate framing. A plain >=4.6.0 check classifies those betas as framing-capable, corrupting byte streams written from a 4.6.0 client to runs or deployments from that window (e.g. hook resumes into long-lived runs created on those betas).

Misclassifying a capable version as incapable is always safe — it just falls back to the legacy raw byte format — so the range errs conservative.

Why this must land on stable (not the release branch)

The equivalent of fix 1 currently exists only as a manual commit on changeset-release/stable (1eae02f). The changesets action regenerates that branch on every push to stable, so the next backport merge would silently drop it and #2426 would ship the corruption bug. Landing it here makes it durable.

Tests

capabilities.test.ts: 4.5.0/4.5.1 and 5.0.0-beta.0/5.0.0-beta.14 read as raw; exact cutoffs 4.6.0 and 5.0.0-beta.15 read as framed; future prereleases above the cutoff (5.1.0-beta.0) recognized as capable.

Note for main

main's cutoff (5.0.0-beta.15) is safe but conservative — it treats stable 4.6.x targets as raw, skipping the framing optimization. A forward-port of the range form can enable it; tracked separately.

🤖 Generated with Claude Code

The framedByteStreams capability was gated at minVersion 4.5.0, but
stable 4.5.0 was published before the framing backport (#2380) merged,
so 4.5.0 deployments cannot unframe framed byte streams — they silently
pipe length-prefixed bytes through to user code. Gate at 4.6.0 instead,
the release that actually ships framing.

Additionally, replace the plain minimum-version check with a semver
range: every 5.0.0-beta.x compares above any 4.x version, but betas
below 5.0.0-beta.15 predate framing, so a plain >=4.6.0 check would
classify them as framing-capable and corrupt byte streams written to
runs or deployments from that window.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@VaguelySerious
VaguelySerious requested review from a team and ijjk as code owners July 3, 2026 00:08
@changeset-bot

changeset-bot Bot commented Jul 3, 2026

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: dcc069a

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

This PR includes changesets to release 16 packages
Name Type
@workflow/core Patch
@workflow/builders Patch
@workflow/cli Patch
@workflow/next Patch
@workflow/nitro Patch
@workflow/vitest Patch
@workflow/web-shared Patch
@workflow/web Patch
workflow Patch
@workflow/world-testing Patch
@workflow/astro Patch
@workflow/nest Patch
@workflow/rollup Patch
@workflow/sveltekit Patch
@workflow/vite Patch
@workflow/nuxt 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

vercel Bot commented Jul 3, 2026

Copy link
Copy Markdown
Contributor

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

Project Deployment Actions Updated (UTC)
example-nextjs-workflow-turbopack Ready Ready Preview, Comment Jul 3, 2026 3:52am
example-nextjs-workflow-webpack Ready Ready Preview, Comment Jul 3, 2026 3:52am
example-workflow Ready Ready Preview, Comment Jul 3, 2026 3:52am
workbench-astro-workflow Ready Ready Preview, Comment Jul 3, 2026 3:52am
workbench-express-workflow Ready Ready Preview, Comment Jul 3, 2026 3:52am
workbench-fastify-workflow Ready Ready Preview, Comment Jul 3, 2026 3:52am
workbench-hono-workflow Ready Ready Preview, Comment Jul 3, 2026 3:52am
workbench-nitro-workflow Ready Ready Preview, Comment Jul 3, 2026 3:52am
workbench-nuxt-workflow Ready Ready Preview, Comment Jul 3, 2026 3:52am
workbench-sveltekit-workflow Ready Ready Preview, Comment Jul 3, 2026 3:52am
workbench-tanstack-start-workflow Ready Ready Preview, Comment Jul 3, 2026 3:52am
workbench-vite-workflow Ready Ready Preview, Comment Jul 3, 2026 3:52am
workflow-docs Ready Ready Preview, Comment, Open in v0 Jul 3, 2026 3:52am
workflow-swc-playground Ready Ready Preview, Comment Jul 3, 2026 3:52am
workflow-tarballs Ready Ready Preview, Comment Jul 3, 2026 3:52am
workflow-web Ready Ready Preview, Comment Jul 3, 2026 3:52am

@github-actions

github-actions Bot commented Jul 3, 2026

Copy link
Copy Markdown
Contributor

🧪 E2E Test Results

Some tests failed

Summary

Passed Failed Skipped Total
✅ ▲ Vercel Production 1077 0 78 1155
✅ 💻 Local Development 1174 0 86 1260
✅ 📦 Local Production 1174 0 86 1260
❌ 🐘 Local Postgres 1173 1 86 1260
✅ 🪟 Windows 105 0 0 105
❌ 🌍 Community Worlds 79 102 9 190
✅ 📋 Other 594 0 36 630
Total 5376 103 381 5860

❌ Failed Tests

🐘 Local Postgres (1 failed)

sveltekit-stable (1 failed):

  • workflowAndStepMetadataWorkflow | wrun_01KWK1P6268NQ1BSNDXA017AWM
🌍 Community Worlds (102 failed)

redis (19 failed):

  • hookWorkflow | wrun_01KWK1KS31DNEDMFRXX2PD3RNJ
  • hookWorkflow is not resumable via public webhook endpoint | wrun_01KWK1M0C9QDZTPEWAXNBHSTC7
  • parallelStepsThenWebhookWorkflow - no hook_conflict from same-tick replay race | wrun_01KWK1MAERB787BM0A2M9G9NV6
  • sleepingWorkflow | wrun_01KWK1N8GJCK3DZ1A8TSPRK02Y
  • 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
  • concurrent hook token conflict - two workflows cannot use the same hook token simultaneously | wrun_01KWK1X6QP96V2J1ZQE16ZYPCN
  • hookGetConflictWorkflow - awaiting hook.getConflict() registers hook without payload | wrun_01KWK1XKD3KBDZGJQDCWNAZF0Z
  • hookGetConflictThenStepParallelWorkflow - hook.getConflict() continuation step runs alongside other steps | wrun_01KWK1XV9G80NB1V576RKWMY6Z
  • hookGetConflictWorkflow - hook.getConflict() resolves with the conflicting run when token is already registered | wrun_01KWK1Y94M071NZ4ENF2QA35FQ
  • hookClaimOnlyMutexWorkflow - hook works as a pure run mutex without payload data | wrun_01KWK1Z5TVD0M385GSYR2MRFMT
  • hookAdoptOwnerResultWorkflow - duplicate adopts the owner result via conflict.returnValue | wrun_01KWK1Z9B9B79E9QW9YEYQRK76
  • hookSignalOwnerWorkflow - duplicate forwards its payload to the owner via resumeHook | wrun_01KWK1ZFEAW4F4J1BGSN65VWGB
  • hookSupersedeOwnerWorkflow - duplicate cancels the owner and claims the released token | wrun_01KWK1ZNAVCG8A5X7S06YTCAW3
  • resume-or-start route pattern - resumeHook retried after start() reaches the new run | wrun_01KWK1ZZBSW45K4J3TKNMV1FR3
  • pages router sleepingWorkflow via pages router
  • resilient start: addTenWorkflow completes when run_created returns 500 | wrun_01KWK25ZBRG1KVB3MX25289SNT

turso (83 failed):

  • addTenWorkflow | wrun_01KWK1JTMKB2YHVDPQ05Y1KE9B
  • addTenWorkflow | wrun_01KWK1JTMKB2YHVDPQ05Y1KE9B
  • deploymentId: 'latest' is a no-op in non-Vercel worlds
  • wellKnownAgentWorkflow (.well-known/agent) | wrun_01KWK1KM0TDDWTGVET4K4GMJ1W
  • should work with react rendering in step
  • promiseAllWorkflow | wrun_01KWK1K2YDNGCPXNWRTFY5H8PT
  • promiseRaceWorkflow | wrun_01KWK1K81A0HGP0KDC7S2YGA53
  • promiseAnyWorkflow | wrun_01KWK1KA94VBCB4BVJXPW216T9
  • importedStepOnlyWorkflow | wrun_01KWK1KXJW6HRT6HC4C9MC6NGD
  • readableStreamWorkflow | wrun_01KWK1KCNPM9CYSC4XWQYCBS80
  • hookWorkflow | wrun_01KWK1KS31DNEDMFRXX2PD3RNJ
  • hookWorkflow is not resumable via public webhook endpoint | wrun_01KWK1M0C9QDZTPEWAXNBHSTC7
  • webhookWorkflow | wrun_01KWK1M5CVBAAGFKDVZ7KS23EV
  • parallelStepsThenWebhookWorkflow - no hook_conflict from same-tick replay race | wrun_01KWK1MAERB787BM0A2M9G9NV6
  • sleepingWorkflow | wrun_01KWK1N8GJCK3DZ1A8TSPRK02Y
  • parallelSleepWorkflow | wrun_01KWK1NRPSB2SWP67P7370Y99E
  • sleepWinsRaceWorkflow | wrun_01KWK1NWM2JA9ND8KCV4E6NV2X
  • stepWinsRaceWorkflow | wrun_01KWK1P03MMDYQ0TVTFP13W64B
  • nullByteWorkflow | wrun_01KWK1P3MTCT482GNFBG2JRT1A
  • workflowAndStepMetadataWorkflow | wrun_01KWK1P6268NQ1BSNDXA017AWM
  • 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_01KWK1RERDSJC5FYEBW8ACRV3K
  • writableForwardedFromWorkflowWorkflow | wrun_01KWK1RW1F5PJ2YE6GQTTA4CQ8
  • writableForwardedFromStepWorkflow | wrun_01KWK1S0EC1A4DWT67WH0SP1VV
  • fetchWorkflow | wrun_01KWK1S405HZTRDP4SSHMYRN52
  • promiseRaceStressTestWorkflow | wrun_01KWK1S7HRRRRHKPZ7XMNM54JF
  • 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 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_01KWK1WPMTNYGXYZ51YNDGTP8Z
  • concurrent hook token conflict - two workflows cannot use the same hook token simultaneously | wrun_01KWK1X6QP96V2J1ZQE16ZYPCN
  • hookGetConflictWorkflow - awaiting hook.getConflict() registers hook without payload | wrun_01KWK1XKD3KBDZGJQDCWNAZF0Z
  • 'hookGetConflictWithPriorStepWorkflow' - hook.getConflict() does not block step execution | wrun_01KWK1XP0V35ZDZ8Z7XSX4VGCT
  • 'hookGetConflictWithParallelStepWorkfl…' - hook.getConflict() does not block step execution | wrun_01KWK1XRJ4222CVP193C5M2HB9
  • hookGetConflictThenStepParallelWorkflow - hook.getConflict() continuation step runs alongside other steps | wrun_01KWK1XV9G80NB1V576RKWMY6Z
  • hookGetConflictWorkflow - hook.getConflict() resolves with the conflicting run when token is already registered | wrun_01KWK1Y94M071NZ4ENF2QA35FQ
  • hookClaimOnlyMutexWorkflow - hook works as a pure run mutex without payload data | wrun_01KWK1Z5TVD0M385GSYR2MRFMT
  • hookAdoptOwnerResultWorkflow - duplicate adopts the owner result via conflict.returnValue | wrun_01KWK1Z9B9B79E9QW9YEYQRK76
  • hookSignalOwnerWorkflow - duplicate forwards its payload to the owner via resumeHook | wrun_01KWK1ZFEAW4F4J1BGSN65VWGB
  • hookSupersedeOwnerWorkflow - duplicate cancels the owner and claims the released token | wrun_01KWK1ZNAVCG8A5X7S06YTCAW3
  • resume-or-start route pattern - resumeHook retried after start() reaches the new run | wrun_01KWK1ZZBSW45K4J3TKNMV1FR3
  • hookDisposeTestWorkflow - hook token reuse after explicit disposal while workflow still running | wrun_01KWK206D7YHA49ZAG68KYJHWP
  • stepFunctionPassingWorkflow - step function references can be passed as arguments (without closure vars) | wrun_01KWK20Q4N276JGWJYRY9SFWNK
  • stepFunctionWithClosureWorkflow - step function with closure variables passed as argument | wrun_01KWK210QWB5SKX8Z002YXX38Z
  • closureVariableWorkflow - nested step functions with closure variables | wrun_01KWK216M30QA6G2PFY91AMFET
  • spawnWorkflowFromStepWorkflow - spawning a child workflow using start() inside a step | wrun_01KWK2194YJT83J5B3DMX7GFRE
  • 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_01KWK21VJD7ZXWX8VHR6S2WW6Y
  • Calculator.calculate - static workflow method using static step methods from another class | wrun_01KWK221P02EY71ENWWDVZXPJ7
  • AllInOneService.processNumber - static workflow method using sibling static step methods | wrun_01KWK228S7H4MR83ZKQ065R8X0
  • ChainableService.processWithThis - static step methods using this to reference the class | wrun_01KWK22G2G16MSDFQJJ2QHW513
  • thisSerializationWorkflow - step function invoked with .call() and .apply() | wrun_01KWK22QJ744GMMTY741MKZNE7
  • customSerializationWorkflow - custom class serialization with WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE | wrun_01KWK22YT36S0WPT8QKNF5SVQN
  • instanceMethodStepWorkflow - instance methods with "use step" directive | wrun_01KWK2360S5D6T1M0GR1NBVA91
  • crossContextSerdeWorkflow - classes defined in step code are deserializable in workflow context | wrun_01KWK23K42RH7G3HCA42VMHXWC
  • stepFunctionAsStartArgWorkflow - step function reference passed as start() argument | wrun_01KWK23WN98S8XZ0R5K7APEJXT
  • cancelRun - cancelling a running workflow | wrun_01KWK243YF9ENPJC5YVHT6H8H2
  • cancelRun via CLI - cancelling a running workflow | wrun_01KWK2494TYFFTKXG2DADHDJAF
  • 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_01KWK24H4K6WQ9MVWW16ZEXN0C
  • hookWithSleepFinalStepWorkflow - step only on final payload | wrun_01KWK24YKRVE94MTAC9FKZX851
  • sleepInLoopWorkflow - sleep inside loop with steps actually delays each iteration | wrun_01KWK257G110BA9H80F9660ZT6
  • sleepWithSequentialStepsWorkflow - sequential steps work with concurrent sleep (control) | wrun_01KWK25JBQPT85Y75XAPN2MCRV
  • importMetaUrlWorkflow - import.meta.url is available in step bundles | wrun_01KWK25TTF0BRME318YPX59J23
  • metadataFromHelperWorkflow - getWorkflowMetadata/getStepMetadata work from module-level helper (#1577) | wrun_01KWK25X41PHMCAHK0YRNVSTY0
  • resilient start: addTenWorkflow completes when run_created returns 500 | wrun_01KWK25ZBRG1KVB3MX25289SNT

Details by Category

✅ ▲ Vercel Production
App Passed Failed Skipped
✅ astro 97 0 8
✅ example 97 0 8
✅ express 97 0 8
✅ fastify 97 0 8
✅ hono 97 0 8
✅ nextjs-turbopack 102 0 3
✅ nextjs-webpack 102 0 3
✅ nitro 97 0 8
✅ nuxt 97 0 8
✅ sveltekit 97 0 8
✅ vite 97 0 8
✅ 💻 Local Development
App Passed Failed Skipped
✅ astro-stable 99 0 6
✅ express-stable 99 0 6
✅ fastify-stable 99 0 6
✅ hono-stable 99 0 6
✅ nextjs-turbopack-canary 86 0 19
✅ nextjs-turbopack-stable 105 0 0
✅ nextjs-webpack-canary 86 0 19
✅ nextjs-webpack-stable 105 0 0
✅ nitro-stable 99 0 6
✅ nuxt-stable 99 0 6
✅ sveltekit-stable 99 0 6
✅ vite-stable 99 0 6
✅ 📦 Local Production
App Passed Failed Skipped
✅ astro-stable 99 0 6
✅ express-stable 99 0 6
✅ fastify-stable 99 0 6
✅ hono-stable 99 0 6
✅ nextjs-turbopack-canary 86 0 19
✅ nextjs-turbopack-stable 105 0 0
✅ nextjs-webpack-canary 86 0 19
✅ nextjs-webpack-stable 105 0 0
✅ nitro-stable 99 0 6
✅ nuxt-stable 99 0 6
✅ sveltekit-stable 99 0 6
✅ vite-stable 99 0 6
❌ 🐘 Local Postgres
App Passed Failed Skipped
✅ astro-stable 99 0 6
✅ express-stable 99 0 6
✅ fastify-stable 99 0 6
✅ hono-stable 99 0 6
✅ nextjs-turbopack-canary 86 0 19
✅ nextjs-turbopack-stable 105 0 0
✅ nextjs-webpack-canary 86 0 19
✅ nextjs-webpack-stable 105 0 0
✅ nitro-stable 99 0 6
✅ nuxt-stable 99 0 6
❌ sveltekit-stable 98 1 6
✅ vite-stable 99 0 6
✅ 🪟 Windows
App Passed Failed Skipped
✅ nextjs-turbopack 105 0 0
❌ 🌍 Community Worlds
App Passed Failed Skipped
✅ mongodb-dev 3 0 3
✅ redis-dev 3 0 3
❌ redis 67 19 0
✅ turso-dev 3 0 3
❌ turso 3 83 0
✅ 📋 Other
App Passed Failed Skipped
✅ e2e-local-dev-nest-stable 99 0 6
✅ e2e-local-dev-tanstack-start-stable 99 0 6
✅ e2e-local-postgres-nest-stable 99 0 6
✅ e2e-local-postgres-tanstack-start-stable 99 0 6
✅ e2e-local-prod-nest-stable 99 0 6
✅ e2e-local-prod-tanstack-start-stable 99 0 6

📋 View full workflow run


Some E2E test jobs failed:

  • Vercel Prod: success
  • Local Dev: success
  • Local Prod: success
  • Local Postgres: failure
  • Windows: success

Check the workflow run for details.

Comment thread .changeset/framing-capability-cutoff.md Outdated
@@ -0,0 +1,6 @@
---
"@workflow/core": patch
"workflow": patch

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no need for workflow in changeset

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

Comment thread .changeset/framing-capability-cutoff.md Outdated
Signed-off-by: Peter Wielander <mittgfu@gmail.com>
@VaguelySerious
VaguelySerious merged commit d0e4191 into stable Jul 3, 2026
92 of 97 checks passed
@VaguelySerious
VaguelySerious deleted the peter/framing-capability-cutoff branch July 3, 2026 23:00
@github-actions github-actions Bot mentioned this pull request Jul 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants