fix(core): finish lifecycle registration guidance and diagnostics

[TooTallNate]

Summary

Final focused follow-up to #4216 and Pranay's review, including the docs caveats requested in the approval.

Documentation

• Add a framework/deployment registration table: Next.js 16.3.0+, shared-server integrations, synchronous Nitro v3 plugins, and the Vercel Build Output API targets whose standalone flow function does not load app startup code.
• Explain next dev restarts and duplicate registrations on other hot-reloading hosts.
• Document runtime/handler module-copy boundaries and .is() checks; correct the custom Error subclass claim in the v5 overview. The examples import FatalError from workflow and WorkflowRunFailedError from workflow/errors.
• Add a leaked-lock warning and a finally/reader-cancellation example. Scope Vercel's automatic drain to error.cause; explain run.returnValue and detached-work exclusions, and that hydrated writable streams still write to their target run.
• Document lifecycle spans and their reporting-failure events.

Small runtime fixes

• Reject registration inside step context and replace the workflow stub's misleading "move this call to a step" guidance with host-startup instructions.
• Format each diagnostic field defensively, preserving a log line even when an error's accessor or toString throws. Distinguish hook-property access from handler failures and log hydration-fallback reasons.
• Correlate lifecycle spans with workflow.run.id / workflow.name and emit workflow.lifecycle.failure events. Isolated reporting errors remain isolated; the docs explain that span status alone is not a reporting-success signal.
• Make QuickJS checkpoint diagnostics best effort so a throwing debug sink cannot suppress completion dispatch after persistence.
• Replace the empty completion-params interface with a type alias.

Coverage and scope

Tests load two genuinely independent lifecycle modules, reject step registration without scheduling hooks, cancel an in-flight readable, verify hostile error diagnostics and span events, and exercise completion with a throwing QuickJS diagnostic sink. The existing nested-operation drain regressions remain in the core suite.

Builder-owned registration, keyed registration, and terminal Run pre-seeding are the larger feature follow-ups identified by the review, rather than part of this fast follow-up. Automatic stream-drain timeouts would also need a cancellation/lifetime contract; this PR documents cleanup explicitly.

Validation

• pnpm test --filter=@workflow/core --filter=workflow --output-logs=errors-only
• pnpm build --output-logs=errors-only (28 tasks)
• pnpm typecheck --output-logs=errors-only (43 tasks)
• pnpm test:docs -t 'lifecycle-hooks|register-lifecycle-hooks|whats-new|tracing' (8 passed)
• Biome checks on changed code, git diff --check, and changeset validation

The local docs link checker could not run because its bundled Bun executable failed to launch; rendered-link validation is left to CI. Preview URLs below use the actual /v5/docs/... route prefix.

Docs Preview

Page	Preview
Lifecycle Hooks guide	Registration, module copies, and stream lifetime
registerLifecycleHooks reference	API guidance and behavior
Tracing	Lifecycle spans
What's New	Richer serialization

Preview links require Vercel team access.

[changeset-bot]

🦋 Changeset detected

Latest commit: 74fbbf6

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	Patch
@workflow/builders	Patch
@workflow/cli	Patch
@workflow/next	Patch
@workflow/nitro	Patch
@workflow/vitest	Patch
@workflow/web-shared	Patch
@workflow/web	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]

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

Project	Deployment	Actions	Updated
example-nextjs-workflow-turbopack	Ready	Preview, v0	Sep 29, 2026 6:20pm UTC
example-nextjs-workflow-webpack	Ready	Preview, v0	Sep 29, 2026 6:20pm UTC
example-workflow	Ready	Preview, v0	Sep 29, 2026 6:20pm UTC
workbench-astro-workflow	Ready	Preview, v0	Sep 29, 2026 6:20pm UTC
workbench-express-workflow	Ready	Preview, v0	Sep 29, 2026 6:20pm UTC
workbench-fastify-workflow	Ready	Preview, v0	Sep 29, 2026 6:20pm UTC
workbench-hono-workflow	Ready	Preview, v0	Sep 29, 2026 6:20pm UTC
workbench-nestjs-workflow	Ready	Preview, v0	Sep 29, 2026 6:20pm UTC
workbench-nitro-workflow	Ready	Preview, v0	Sep 29, 2026 6:20pm UTC
workbench-nuxt-workflow	Ready	Preview, v0	Sep 29, 2026 6:20pm UTC
workbench-python-workflow	Ready	Preview, v0	Sep 29, 2026 6:20pm UTC
workbench-sveltekit-workflow	Ready	Preview, v0	Sep 29, 2026 6:20pm UTC
workbench-tanstack-start-workflow	Ready	Preview, v0	Sep 29, 2026 6:20pm UTC
workbench-vite-workflow	Ready	Preview, v0	Sep 29, 2026 6:20pm UTC
workflow-docs	Ready	Preview, v0	Sep 29, 2026 6:20pm UTC
workflow-swc-playground	Ready	Preview, v0	Sep 29, 2026 6:20pm UTC
workflow-tarballs	Ready	Preview, v0	Sep 29, 2026 6:20pm UTC
workflow-web	Ready	Preview, v0	Sep 29, 2026 6:20pm UTC

[github-actions]

📊 Workflow Benchmarks

commit 74fbbf6 · Tue, 29 Sep 2026 18:35:28 GMT · run logs

Backend: vercel · app: nextjs-turbopack

Metric	Scenario	Best (ms)	P75 (ms)	P90 (ms)	P99 (ms)	Samples
TTFS	step	2718 (+57%) 🔻	2883 🔴 (+46%) 🔻	2924 🔴 (+46%) 🔻	3124 🔴 (+25%) 🔻	30
TTFS	stream	2669 (+48%) 🔻	2847 🔴 (+47%) 🔻	2872 🔴 (+47%) 🔻	2892 🔴 (+47%) 🔻	30
TTFS	hook + stream	653 (+21%) 🔻	3249 🔴 (+44%) 🔻	3338 🔴 (+46%) 🔻	3560 🔴 (-35%) 💚	30
Fan-out TTFS	Promise.all(100 steps)	660 (+6.3%)	865 (-63%) 💚	1046 (-55%) 💚	3415 (+37%) 🔻	10
Fan-out TTLS	Promise.all(100 steps)	1858 (+8.7%)	3865 (-1.9%)	4620 (-28%) 💚	6928 (-21%) 💚	10
STSO	1020 steps (inline)	89 (-23%) 💚	142 (-4.1%)	160 (-2.4%)	226 (+4.6%)	1019
WO	1020 steps	141040 (-6.4%)	141040 (-6.4%)	141040 (-6.4%)	141040 (-6.4%)	1
CRTT	first chunk (pooled)	59 (-4.8%)	98 (±0%)	116 (+6.4%)	710 (+477%) 🔻	28

Streams

Scenario	CRTT 1st	p75	p90	p99	CDV max	iters
paced control (100/s, 60B)	85 (+4%)	124 (+1%)	151 (-7%)	287 (+16%)	122 (+7%)	10
size sweep (100/s, 160B-12KB)	85.5 (+4%)	120 (-18%)	229 (+22%)	683 (+82%)	94 (-37%)	10
replay gateway-gpt-5.4-nano-2000t (1x)	98 (+13%)	120 (-11%)	140 (-23%)	208 (-74%)	167 (-67%)	3
replay eve-gpt-5.6-sol-2000t (1x)	86.5 (+8%)	129 (-85%)	155 (-95%)	266 (-97%)	182 (-92%)	2
replay eve-gpt-5.6-sol-2000t (2x)	110 (+9%)	170 (±0%)	221 (-53%)	409 (-65%)	300 (-43%)	3

📈 STSO distribution vs main (inline / queue-hop histograms)

1020 steps (inline)

Cumulative STSO time: main 150220ms → this run 140705ms (Δ -9515ms, -6%)

 50-100 ms  ┃                         main   0  this   1    +1
100-150 ms  ██████████████████████░┃  main 791  this 844   +53
150-200 ms  ███┃██                    main 214  this 156   -58
200-250 ms  ┃                         main  11  this   9    -2
250-300 ms  ┃                         main   0  this   6    +6
300-350 ms  ┃                         main   0  this   2    +2
350-400 ms  ┃                         main   2  this   0    -2
400-450 ms  ┃                         main   0  this   1    +1
550-600 ms  ┃                         main   1  this   0    -1

📈 CRTT drill-down vs main (RTT distributions & profiles)

variant  RTT 1ms→5s+             avg        p50         p90         p99     n
control  ······▇█▁····     106 (±0%)  103 (+2%)   151 (-7%)  287 (+16%)  3000
sweep    ······██▁▁···   113.4 (-9%)  99 (-17%)  229 (+22%)  683 (+82%)  3000
gw 1x    ·····▁██▁····  103.6 (-18%)  101 (-9%)  140 (-23%)  208 (-74%)  5295
eve 1x   ·····▁▇█▁····  110.4 (-79%)  100 (+9%)  155 (-95%)  266 (-97%)  5186
eve 2x   ·····▁▄█▂····  134.6 (-19%)  123 (-2%)  221 (-53%)  409 (-65%)  7779

RTT over stream progress (avg per tenth of stream, bars scaled min→max):

control  ██▄▂▁▂▂▁▃▂  96–125ms
sweep    █▅▁▂▂▁▁▁▂▂  100–164ms
gw 1x    ▄▅▁▅▅▆██▆▃  95–110ms
eve 1x   ▃▁▄▇▁▄▄█▃▅  100–123ms
eve 2x   ▃▁▆▃▂▅█▆▆▄  108–162ms

RTT by chunk size (avg per log size bin, ~160B → ~12KB serialized, bars scaled min→max):

sweep  ▇█▅▂▄▅▁  112–115ms

Delivery jitter over stream progress (avg positive CDV per tenth of stream, bars scaled min→max):

control  █▅▆▂▄▃▁▄▄▃  26–41ms
sweep    ▃▂▆▆▄▁▇█▂▁  38–48ms
gw 1x    ▄▄▂▁▅▆█▅▁▃  27–35ms
eve 1x   ▁▃▄▅▄█▅▆▄▆  19–25ms
eve 2x   ▆▂▄▅▄▇█▁▇▇  20–26ms

📜 Previous results (1)

6b584a8

Fri, 25 Sep 2026 22:37:46 GMT · run logs

vercel / nextjs-turbopack

Metric	Scenario	Best (ms)	P75 (ms)	P90 (ms)	P99 (ms)	Samples
TTFS	step	406 (-77%) 💚	2516 🔴 (+33%) 🔻	2852 🔴 (+49%) 🔻	2987 🔴 (+54%) 🔻	30
TTFS	stream	354 (-15%) 💚	2776 🔴 (+47%) 🔻	2864 🔴 (+50%) 🔻	2908 🔴 (+52%) 🔻	30
TTFS	hook + stream	801 (-10%)	2673 🔴 (+23%) 🔻	2699 🔴 (+15%)	2813 🔴 (+16%) 🔻	30
Fan-out TTFS	Promise.all(100 steps)	606 (-0.7%)	882 (+1.8%)	901 (-61%) 💚	2832 (+19%) 🔻	10
Fan-out TTLS	Promise.all(100 steps)	3061 (+16%) 🔻	3902 (-19%) 💚	5529 (-33%) 💚	9928 (+13%)	10
STSO	1020 steps (inline)	104 (-1.9%)	154 (+11%)	173 (+12%)	296 (+34%) 🔻	1019
WO	1020 steps	154248 (+11%)	154248 (+11%)	154248 (+11%)	154248 (+11%)	1
CRTT	first chunk (pooled)	76 (+25%) 🔻	126 (+12%)	143 (-28%) 💚	159 (-40%) 💚	28

Streams

Scenario	CRTT 1st	p75	p90	p99	CDV max	iters
paced control (100/s, 60B)	92.5 (-24%)	163 (-43%)	231 (-70%)	780 (-38%)	165 (-19%)	10
size sweep (100/s, 160B-12KB)	104 (+10%)	155 (-28%)	219 (-34%)	453 (-10%)	167 (-14%)	10
replay gateway-gpt-5.4-nano-2000t (1x)	119 (+23%)	154 (-8%)	184 (-20%)	272 (-34%)	215 (-42%)	3
replay eve-gpt-5.6-sol-2000t (1x)	144 (+81%)	167 (-6%)	200 (-21%)	515 (+5%)	566 (+41%)	2
replay eve-gpt-5.6-sol-2000t (2x)	106 (+6%)	198 (-19%)	263 (-24%)	359 (-55%)	268 (-29%)	3

ℹ️ Metric definitions & methodology

_{Streams: first-chunk RTT (the stream-open path, before any buffering/backpressure), CRTT percentiles, and worst delivery stall (CDV max). Cells are medians across iterations; per-run values in the artifacts. No 🔴/🟢 marks until targets attach.}

_{The collapsed STSO distribution section above buckets every step gap, split inline (same warm process — pure framework overhead) vs queue-hop (fresh process — dispatch, reinit, replay). █ = main, ┃ = this run, ░ = fill.}

_{The collapsed CRTT drill-down: per-variant RTT histograms (fixed log bins, · = empty) and mean RTT/positive-CDV profile lines over stream progress and chunk size. Histograms, avgs, and profiles merge exactly across runs; p50–p99 are percentile-of-percentiles. Per-index rows live in the artifacts.}

_{Best/P75/P90/P99 deltas compare against the most recent benchmark run on main at the time of this run. 🔻 flags a delta worse than +15%, 💚 one better than −15%.}

_{Metrics — TTFS: time to first step body (in-deployment start() → first step body) · Fan-out TTFS: fan-out time to first step (in-deployment start() → first of the parallel step bodies to complete) · Fan-out TTLS: fan-out time to last step (in-deployment start() → last of the parallel step bodies to complete, i.e. when the Promise.all resolves) · STSO: step-to-step overhead (gap between consecutive step bodies) · WO: workflow overhead (whole-run time outside step bodies, in-deployment anchored) · CRTT: chunk round-trip time (per-chunk write → read latency, one clock domain: deployment → stream backend → same deployment) · CDV: chunk delay variation / delivery jitter (inter-arrival gap minus inter-write gap per seq-adjacent pair; skew-free; the row is each run's MAX positive value, so one stall moves it)}

_{Scenarios — step: one trivial no-op step, no stream; no hooks, so the run stays in turbo mode (in-process fast path) · stream: one streaming step; no hooks, so the run stays in turbo mode (in-process fast path) · hook + stream: registers a hook before one step, which exits turbo mode (dispatch path) · 1020 steps: 1020 trivial sequential steps; STSO is measured between consecutive steps in the given step ranges, and WO is the whole-run overhead outside step bodies · Promise.all(100 steps): 100 trivial no-op steps started together in a single Promise.all; Fan-out TTFS is the first of them to complete and Fan-out TTLS the last, both from the in-deployment clientStart, so their gap is the spread the runtime adds across the fan-out · paced control (100/s, 60B): the control: 300 tiny (~60B) deltas metronome-paced at 100/s — zero workload structure, so it reads the transport floor and flush cadence, and disambiguates transport-wide vs workload-specific when a replay row moves · size sweep (100/s, 160B-12KB): same pacing as the control with deltas padded in rotation across seven log-spaced sizes (~160B–12KB) — rotation decouples size from stream position, so it isolates whether chunk size causes latency · replay gateway-gpt-5.4-nano-2000t (1x): raw provider SSE cadence captured at the AI gateway boundary (gpt-5.4-nano, the most popular gateway model; per-token deltas p50 208B = the modal production chunk size), replayed exactly as measured — the typical customer's workload; its CDV is the typical customer's real delivery jitter · replay eve-gpt-5.6-sol-2000t (1x): a captured eve turn (gpt-5.6-sol, the most-used demanding eve model; ~2000 output tokens = production p50 turn length) replayed exactly as measured — eve's envelope protocol re-ships the cumulative message so sizes ramp 142B→13KB; the demanding outlier tenant's reality · replay eve-gpt-5.6-sol-2000t (2x): the same eve capture at 2x — the headroom/stress row; real fast-tier models emit the same chunk sizes at proportionally higher rate, so time compression is a faithful speed model · first chunk (pooled): every run's seq-0 RTT pooled across all stream scenarios — the first chunk precedes any workload differentiation, so pooling samples one shared stream-open path with exact percentiles}

_{Replay cadences (semantic sha256) — eve-gpt-5.6-sol-2000t eaf22f5946e7c61f3c65c7006d550df180cfabd4e706254a09f22aec0cfb420d · gateway-gpt-5.4-nano-2000t 6f24ac518b6b83ff1d0e85a5fe78230db192716d66a7fc6b2fe022752001d041}

_{🔴 marks a percentile over its target (within target is left unmarked). Targets (p75/p90/p99, ms) — TTFS 200/300/600}

_{All timestamps are deployment-side; runs are triggered in-deployment, so the CI runner and api.vercel.com sit outside every measured window. TTFS = start() → first step body (includes dispatch + any cold start); Fan-out TTFS/TTLS = first/last step completion of one Promise.all from the same anchor (the gap is the runtime’s fan-out spread); STSO/WO between step bodies; CRTT inside the workflow (excludes the api.vercel.com read path).}

_{Cold starts stay in the numbers (real bursty-workload latency, inflates P75+); Best is the warm floor.}

[github-actions]

🧪 E2E Test Results

✅ All tests passed

⚠️ Flaky E2E Tests (passed on retry)

These tests failed at least once and passed on a retry. A recurring entry here is a real race worth investigating.

• completes within timeout (sveltekit · vercel-prod / vercel / node / production)
• payloads delivered before the takeover stay with the victim; the iterator then throws (nextjs-webpack · local-dev / local / node / stable)
• resumes in flight during the takeover are never lost: each lands in exactly one log (nextjs-webpack · local-dev / local / node / stable)
• takes the token over: the victim is woken and rejects with HookForceClaimedError, resumes reach the claimer (nextjs-webpack · local-dev / local / node / stable)

🛠 Infra Events (absorbed by the harness)

Platform anomalies the e2e harness detected and worked around (e.g. a run the queue never picked up, replaced by a fresh run). Clustered timestamps indicate a backend blip; a steady drip indicates a platform issue worth escalating.

• run-pickup-stall · runs app-generated source against a registered step (tanstack-start) · at 18:20:26Z · abandoned wrun_01M3Q6AKDH9C0YCZW7N8HWRH16
• cold-start-warmup · suite warmup (tanstack-start) · at 18:20:34Z · abandoned wrun_01M3Q6AKDFGD7N11CND5KE1JB6
• run-pickup-stall · hookCleanupTestWorkflow - hook token reuse after workflow completion (nextjs-webpack) · at 18:28:50Z · abandoned wrun_01M3Q6SZQQ1595XGCAQREHCKC3

E2E Test Summary

Summary

	Passed	Failed	Skipped	Total
✅ ▲ Vercel Production	3904	0	875	4779
✅ 💻 Local Development	4406	0	550	4956
✅ 📦 Local Production	4406	0	550	4956
✅ 🐘 Local Postgres	4406	0	550	4956
✅ 🪟 Windows	342	0	12	354
✅ 🌐 Cross-language Conformance	68	0	84	152
✅ dynamic-runs	0	0	0	0
✅ vercel-http-transport	879	0	183	1062
✅ vercel-multi-region	27	0	0	27
✅ vercel-ws-transport	595	0	113	708
Total	19033	0	2917	21950

Details by Category

✅ ▲ Vercel Production

App	Passed	Failed	Skipped
✅ astro-node	142	0	35
✅ astro-quickjs	142	0	35
✅ example-node	142	0	35
✅ example-quickjs	142	0	35
✅ express-node	142	0	35
✅ express-quickjs	142	0	35
✅ fastify-node	142	0	35
✅ fastify-quickjs	142	0	35
✅ hono-node	142	0	35
✅ hono-quickjs	142	0	35
✅ nest-node	142	0	35
✅ nest-quickjs	142	0	35
✅ nextjs-turbopack-node	169	0	8
✅ nextjs-turbopack-quickjs	169	0	8
✅ nextjs-webpack-node	169	0	8
✅ nextjs-webpack-quickjs	169	0	8
✅ nitro-node	142	0	35
✅ nitro-quickjs	142	0	35
✅ nuxt-node	142	0	35
✅ nuxt-quickjs	142	0	35
✅ python-node	66	0	111
✅ sveltekit-node	161	0	16
✅ sveltekit-quickjs	161	0	16
✅ tanstack-start-node	142	0	35
✅ tanstack-start-quickjs	142	0	35
✅ vite-node	142	0	35
✅ vite-quickjs	142	0	35

✅ 💻 Local Development

App	Passed	Failed	Skipped
✅ astro-stable-node	148	0	29
✅ astro-stable-quickjs	148	0	29
✅ express-stable-node	148	0	29
✅ express-stable-quickjs	148	0	29
✅ fastify-stable-node	148	0	29
✅ fastify-stable-quickjs	148	0	29
✅ hono-stable-node	148	0	29
✅ hono-stable-quickjs	148	0	29
✅ nest-stable-node	148	0	29
✅ nest-stable-quickjs	148	0	29
✅ nextjs-turbopack-canary-node	176	0	1
✅ nextjs-turbopack-canary-quickjs	176	0	1
✅ nextjs-turbopack-stable-node	176	0	1
✅ nextjs-turbopack-stable-quickjs	176	0	1
✅ nextjs-webpack-canary-node	176	0	1
✅ nextjs-webpack-canary-quickjs	176	0	1
✅ nextjs-webpack-stable-node	176	0	1
✅ nextjs-webpack-stable-quickjs	176	0	1
✅ nitro-stable-node	148	0	29
✅ nitro-stable-quickjs	148	0	29
✅ nuxt-stable-node	148	0	29
✅ nuxt-stable-quickjs	148	0	29
✅ sveltekit-stable-node	167	0	10
✅ sveltekit-stable-quickjs	167	0	10
✅ tanstack-start-node	148	0	29
✅ tanstack-start-quickjs	148	0	29
✅ vite-stable-node	148	0	29
✅ vite-stable-quickjs	148	0	29

✅ 📦 Local Production

App	Passed	Failed	Skipped
✅ astro-stable-node	148	0	29
✅ astro-stable-quickjs	148	0	29
✅ express-stable-node	148	0	29
✅ express-stable-quickjs	148	0	29
✅ fastify-stable-node	148	0	29
✅ fastify-stable-quickjs	148	0	29
✅ hono-stable-node	148	0	29
✅ hono-stable-quickjs	148	0	29
✅ nest-stable-node	148	0	29
✅ nest-stable-quickjs	148	0	29
✅ nextjs-turbopack-canary-node	176	0	1
✅ nextjs-turbopack-canary-quickjs	176	0	1
✅ nextjs-turbopack-stable-node	176	0	1
✅ nextjs-turbopack-stable-quickjs	176	0	1
✅ nextjs-webpack-canary-node	176	0	1
✅ nextjs-webpack-canary-quickjs	176	0	1
✅ nextjs-webpack-stable-node	176	0	1
✅ nextjs-webpack-stable-quickjs	176	0	1
✅ nitro-stable-node	148	0	29
✅ nitro-stable-quickjs	148	0	29
✅ nuxt-stable-node	148	0	29
✅ nuxt-stable-quickjs	148	0	29
✅ sveltekit-stable-node	167	0	10
✅ sveltekit-stable-quickjs	167	0	10
✅ tanstack-start-node	148	0	29
✅ tanstack-start-quickjs	148	0	29
✅ vite-stable-node	148	0	29
✅ vite-stable-quickjs	148	0	29

✅ 🐘 Local Postgres

App	Passed	Failed	Skipped
✅ astro-stable-node	148	0	29
✅ astro-stable-quickjs	148	0	29
✅ express-stable-node	148	0	29
✅ express-stable-quickjs	148	0	29
✅ fastify-stable-node	148	0	29
✅ fastify-stable-quickjs	148	0	29
✅ hono-stable-node	148	0	29
✅ hono-stable-quickjs	148	0	29
✅ nest-stable-node	148	0	29
✅ nest-stable-quickjs	148	0	29
✅ nextjs-turbopack-canary-node	176	0	1
✅ nextjs-turbopack-canary-quickjs	176	0	1
✅ nextjs-turbopack-stable-node	176	0	1
✅ nextjs-turbopack-stable-quickjs	176	0	1
✅ nextjs-webpack-canary-node	176	0	1
✅ nextjs-webpack-canary-quickjs	176	0	1
✅ nextjs-webpack-stable-node	176	0	1
✅ nextjs-webpack-stable-quickjs	176	0	1
✅ nitro-stable-node	148	0	29
✅ nitro-stable-quickjs	148	0	29
✅ nuxt-stable-node	148	0	29
✅ nuxt-stable-quickjs	148	0	29
✅ sveltekit-stable-node	167	0	10
✅ sveltekit-stable-quickjs	167	0	10
✅ tanstack-start-node	148	0	29
✅ tanstack-start-quickjs	148	0	29
✅ vite-stable-node	148	0	29
✅ vite-stable-quickjs	148	0	29

✅ 🪟 Windows

App	Passed	Failed	Skipped
✅ nextjs-turbopack-node	171	0	6
✅ nextjs-turbopack-quickjs	171	0	6

✅ 🌐 Cross-language Conformance

App	Passed	Failed	Skipped
✅ python	68	0	84

✅ dynamic-runs

App	Passed	Failed	Skipped
✅ astro-vercel	0	0	0
✅ example-vercel	0	0	0
✅ express-vercel	0	0	0
✅ fastify-vercel	0	0	0
✅ hono-vercel	0	0	0
✅ nest-vercel	0	0	0
✅ nextjs-turbopack-vercel	0	0	0
✅ nextjs-webpack-vercel	0	0	0
✅ nitro-vercel	0	0	0
✅ nuxt-vercel	0	0	0
✅ sveltekit-vercel	0	0	0
✅ tanstack-start-vercel	0	0	0
✅ vite-vercel	0	0	0

✅ vercel-http-transport

App	Passed	Failed	Skipped
✅ example	142	0	35
✅ express	142	0	35
✅ hono	142	0	35
✅ nextjs-turbopack	169	0	8
✅ nitro	142	0	35
✅ vite	142	0	35

✅ vercel-multi-region

App	Passed	Failed	Skipped
✅ nextjs-turbopack	27	0	0

✅ vercel-ws-transport

App	Passed	Failed	Skipped
✅ example	142	0	35
✅ express	142	0	35
✅ nextjs-turbopack	169	0	8
✅ vite	142	0	35

---

📋 View full workflow run

[github-actions]

Sim World

Simulated world deterministic testing for races. Traces

🟠 world-sim scenario book — 1 fail of 42 total

fence=per-spec

scenario	outcome	events	virt	replay	violations
✅ smoke-no-steps	completed	3	0ms	ok	0
✅ smoke-one-step	completed	6	0ms	ok	0
✅ hook-at-step-started	completed	12	0ms	ok	0
✅ hook-at-step-completed	completed	12	0ms	ok	0
✅ hook-at-hook-created	completed	12	0ms	ok	0
✅ deadline-hook-wins	completed	7	1.0h	ok	0
✅ deadline-expires	completed	7	1.0h	ok	0
✅ step-vs-timer-early-settlement	completed	8	1.0h	ok	0
✅ long-sleep	completed	11	30.0d	ok	0
✅ hook-never-arrives	stalled	3	0ms	skipped	0
✅ step-retries-twice	completed	10	2.0s	ok	0
✅ parallel-steps	completed	9	0ms	ok	0
✅ hook-on-execution-state	completed	12	0ms	ok	0
✅ peek-hook-before-branch	completed	12	0ms	ok	0
✅ peek-hook-after-branch	completed	12	0ms	ok	0
✅ peek-hook-at-registration	completed	12	0ms	ok	0
✅ race-hook-before-probe	completed	12	0ms	ok	0
✅ race-hook-after-probe	completed	12	0ms	ok	0
✅ race-duplicate-delivery	completed	13	0ms	ok	0
✅ attr-hook-before-step	completed	11	0ms	ok	0
✅ attr-hook-after-step	completed	11	0ms	ok	0
✅ attr-from-step-body	completed	13	0ms	ok	0
✅ fork-hook-after-timeout	completed	14	1.0m	ok	0
✅ fork-hook-before-timeout	completed	14	1.0m	ok	0
✅ count-hook-after-timeout	completed	17	1.0m	ok	0
✅ count-hook-before-timeout	completed	20	1.0m	ok	0
✅ stale-read-step-count-fork	completed	20	1.0m	ok	0
✅ stale-read-equal-step-counts	completed	14	1.0m	ok	0
✅ step-vs-step-fork	completed	12	0ms	ok	0
✅ step-vs-step-fork-fenced	completed	12	0ms	ok	0
✅ fence-catches-benign-direction	completed	12	5ms	ok	0
✅ in-flight-before-decision	completed	17	1.0m	ok	0
❌ in-flight-before-decision-counted	completed	17	1.0m	ok	0
✅ in-flight-after-decision	completed	19	2.0m	ok	0
✅ stale-read-step-count-fork-fenced	completed	20	1.0m	ok	0
✅ fork-hook-wins	completed	13	1.0m	ok	0
✅ fork-timeout-wins	completed	13	1.0m	ok	0
✅ unclaimed-payload-under-fork	completed	17	1.0m	ok	0
✅ claimed-payload-under-fork	completed	17	1.0m	ok	0
✅ writers-independent-step-bodies	completed	12	0ms	ok	0
✅ writers-scripted-tempo	completed	12	0ms	ok	0
✅ cancel-mid-step	cancelled	7	0ms	skipped	0

Full trace: world-sim.txt

[Copilot]

Copilot review overview

🔵 Needs a closer look

Two moderate lifecycle dispatch and telemetry-isolation issues remain unresolved.

Review effort: Lite
Findings: None

What changed in this PR

Completes lifecycle-hook registration guidance and strengthens diagnostics, tracing, stream cleanup, and QuickJS completion handling.

Changes:

• Improves registration validation and startup guidance.
• Hardens lifecycle diagnostics, telemetry, hydration, and completion reporting.
• Expands documentation and regression coverage.

File	Description
packages/​workflow/​src/​api-workflow.ts	Updates workflow-context registration errors.
packages/​workflow/​src/​api-workflow.test.ts	Tests registration guidance.
packages/​workflow/​README.md	Documents lifecycle registration.
packages/​core/​src/​runtime/​quickjs-lifecycle.test.ts	Tests diagnostic-sink resilience.
packages/​core/​src/​runtime/​quickjs-entrypoint.ts	Makes checkpoint diagnostics best effort.
packages/​core/​src/​runtime/​lifecycle-hooks.ts	Adds validation, diagnostics, tracing, and hydration reporting.
packages/​core/​src/​runtime/​lifecycle-hooks.test.ts	Adds lifecycle regression coverage.
packages/​core/​src/​runtime/​lifecycle-hooks-module-copies.test.ts	Tests cross-module registration.
packages/​core/​README.md	Documents host-startup requirements.
docs/​content/​docs/​v5/​whats-new.mdx	Corrects error serialization guidance.
docs/​content/​docs/​v5/​observability/​tracing.mdx	Documents lifecycle spans and failure events.
docs/​content/​docs/​v5/​observability/​lifecycle-hooks.mdx	Expands framework and stream guidance.
docs/​content/​docs/​v5/​api-reference/​workflow-api/​register-lifecycle-hooks.mdx	Updates API registration documentation.
.changeset/​lifecycle-registration-guidance.md	Records release metadata.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

Framework	Flow route	Step reg.	Framework output
hono	265.9 KiB (±0)	97.2 KiB (+29 B)	1.98 MiB (+204 B)
nextjs-turbopack	273.3 KiB (±0)	426 B (±0)	979.2 KiB (+164 B)

About these numbers

Sizes are gzip; parentheses show the change against main.
Flow route and Step reg. gate this job, on raw bytes rather than the gzip shown, at max(2%, 50.0 KiB). Framework output is informational.

74fbbf6 · run