[core] Make `hook.metadata` a lazy Promise getter by pranaygp · Pull Request #3988 · vercel/workflow

pranaygp · 2026-09-04T20:31:12Z

Summary & Motivation

Hydrating a hook's metadata is a decrypting READ: it needs the owning run's payload keys, and resolving those costs a run fetch plus a run-key API round trip (~350ms). getHookByToken() did that work eagerly on every lookup that found a metadata-bearing hook, so callers that only wanted runId/token paid for it anyway — and so did hook resumption, which never reads metadata at all.

hook.metadata is now a getter that returns a memoized Promise, the same shape as run.returnValue. The lookup is one read again; the hydration and the key resolution behind it happen on first access, or never.

const hook = await getHookByToken(token); // one read, no key work
const metadata = await hook.metadata;     // hydrates here, memoized

Picks up @barbakini's "skip metadata lookups in all the places we can" (vercel/eve#3043) and @pranaygp's "+1 here on make the metadata lookup a lazy promise getter in hook".

What changed

getHookByToken() returns a HookWithLazyMetadata (exported from workflow/api): one hooks.getByToken, nothing else. It no longer mutates the World's record — the returned object is a shallow copy carrying the accessor.
resumeWebhook() is the one resume path that must read metadata (respondWith lives there), so it awaits the getter. Behavior is unchanged: a default webhook that stored no metadata still resolves undefined with no key lookup and still lets resumeHook seal to the run's public key, and a metadata-bearing webhook still resolves the run key exactly once end to end — the key the hydration resolved is reused for the payload write.
resumeHook()'s returned hook gets the same accessor. Previously it handed back the raw record, whose metadata was still the serialized bytes; it now hydrates lazily, which costs nothing when unread.
getHookByTokenWithKey is gone, replaced by withLazyMetadata + a direct hooks.getByToken. The durable write-then-wake resume path itself is untouched.

Breaking change

hook.metadata must be awaited. Like run.returnValue, the accessor is non-enumerable, so it is absent from { ...hook } and JSON.stringify(hook) — that's deliberate: an incidental spread would otherwise kick off hydration nobody awaits, and an unconsumed rejected Promise takes the process down. Forward the awaited value explicitly if you need to serialize it. The World-level Hook type is untouched; world.hooks.getByToken still returns raw serialized metadata.

Test Plan

New packages/core/src/runtime/get-hook-by-token.test.ts (9 tests) covers: a lookup costs exactly one read even with metadata present; first access hydrates and memoizes, deriving read-side keys from the stored resume context with no run read; a metadata-less hook resolves undefined with no I/O; the pre-resumeContext fallback reads the run only on access; a hydration failure surfaces on await, not on lookup; a failed lookup still propagates; the World's record is left untouched; spread/JSON.stringify don't trigger hydration; and a resumed hook carries the accessor without double-wrapping.

The existing resume-hook*.test.ts suites pin the resume behavior that must not move — in particular that a default webhook pays no key lookup and seals, and that a metadata-bearing webhook resolves the key exactly once. All 64 tests across the four hook suites pass, and the full packages/core unit suite is green (2350 passed, 3 expected fail). E2E hook tests were updated for the new access shape.

Docs Preview

Page	v5
`getHookByToken`	/v5/docs/api-reference/workflow-api/get-hook-by-token

Only the v5 page is updated — the change ships in the 5.x beta, and v4 documents the shipped stable API. createHook's metadata option gains a line about reading it back, which renders from TSDoc on /v5/docs/api-reference/workflow/create-hook.

🤖 Generated with Claude Code

changeset-bot · 2026-09-04T20:31:17Z

🦋 Changeset detected

Latest commit: b89b982

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	Major
workflow	Major
@workflow/world-testing	Patch
@workflow/builders	Patch
@workflow/cli	Patch
@workflow/next	Patch
@workflow/nitro	Patch
@workflow/vitest	Patch
@workflow/web-shared	Patch
@workflow/web	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 · 2026-09-04T20:31:25Z

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

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

Copilot

🟡 Changes recommended

The exported HookWithLazyMetadata.metadata type currently doesn’t reflect that it can resolve to undefined, which contradicts the implementation and docs and can mislead API consumers.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR updates the core runtime hook API so hook.metadata is hydrated lazily via a memoized Promise getter, avoiding the run fetch + run-key round trip unless a caller actually reads metadata. This keeps hot paths like hook resumption at a single hooks.getByToken read while preserving existing webhook behavior that depends on metadata (respondWith).

Changes:

Introduced HookWithLazyMetadata and updated getHookByToken() / resumeHook() to return hooks with metadata as a lazy, non-enumerable Promise getter.
Updated resumeWebhook() to explicitly await hook.metadata (the one resume path that needs metadata) and to reuse the derived read-side key for the payload write.
Added/updated unit + e2e + docs coverage to reflect the new access pattern and to assert “single read unless accessed”.

File summaries

File	Description
packages/workflow/src/api.ts	Re-exports `HookWithLazyMetadata` from the public `workflow/api` surface.
packages/core/src/runtime/resume-hook.ts	Implements lazy metadata accessor, updates hook lookup/resume return types, and reuses metadata-derived keys in `resumeWebhook`.
packages/core/src/runtime/resume-hook.parallel.test.ts	Updates test commentary to match the new inline by-token fetch behavior.
packages/core/src/runtime/resume-hook.fast-path.test.ts	Updates test commentary for the new “await metadata” behavior on default webhooks.
packages/core/src/runtime/get-hook-by-token.test.ts	Adds focused unit tests covering lazy hydration, memoization, I/O behavior, and non-enumerability.
packages/core/src/runtime.ts	Re-exports `HookWithLazyMetadata` from `@workflow/core/runtime`.
packages/core/src/create-hook.ts	Updates API docs to tell users `hook.metadata` must be awaited outside the workflow.
packages/core/e2e/e2e.test.ts	Updates e2e call sites to `await hook.metadata` when reading custom metadata.
packages/core/e2e/e2e-region.test.ts	Updates multi-region e2e assertions to `await hook.metadata`.
docs/content/docs/v5/api-reference/workflow-api/get-hook-by-token.mdx	Documents the new lazy Promise getter semantics and updates examples/return type.
.changeset/lazy-hook-metadata-getter.md	Declares a major breaking change and explains the new `hook.metadata` semantics.

Review details

Files reviewed: 11/11 changed files
Comments generated: 1
Review effort level: Lite

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

+   * The hook's user-defined metadata, hydrated on first access and memoized.
+   * Resolves `undefined` when the hook carries no metadata.
+   */
+  readonly metadata: Promise<unknown>;


github-actions · 2026-09-04T20:47:48Z

🧪 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.

addTenWorkflow (tanstack-start)
cancelRun via CLI - cancelling a running workflow (fastify)
deploymentId: 'latest' is a no-op in non-Vercel worlds (nextjs-webpack)
step-return-value serialization failure is catchable in workflow code (nitro)

🛠 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.

cold-start-warmup · suite warmup (tanstack-start) · at 21:04:52Z · abandoned wrun_01M1Q3SANBZJ3VC3M5Y667162Z
run-pickup-stall · hookCleanupTestWorkflow - hook token reuse after workflow completion (nextjs-webpack) · at 21:09:27Z · abandoned wrun_01M1Q423886AQCNR29JNA2JPX0

E2E Test Summary

Summary

	Passed	Skipped	Total
✅ ▲ Vercel Production	3636	684	4320
✅ 💻 Local Development	3922	558	4480
✅ 📦 Local Production	3922	558	4480
✅ 🐘 Local Postgres	3922	558	4480
✅ 🪟 Windows	320	0	320
✅ 🌐 Cross-language Conformance	68	73	141
✅ vercel-http-transport	817	143	960
✅ vercel-multi-region	27	0	27
✅ vercel-ws-transport	553	87	640
Total	17187	2661	19848

Details by Category

✅ ▲ Vercel Production

App	Passed	Skipped
✅ astro-node	132	28
✅ astro-quickjs	132	28
✅ example-node	132	28
✅ example-quickjs	132	28
✅ express-node	132	28
✅ express-quickjs	132	28
✅ fastify-node	132	28
✅ fastify-quickjs	132	28
✅ hono-node	132	28
✅ hono-quickjs	132	28
✅ nest-node	132	28
✅ nest-quickjs	132	28
✅ nextjs-turbopack-node	157	3
✅ nextjs-turbopack-quickjs	157	3
✅ nextjs-webpack-node	157	3
✅ nextjs-webpack-quickjs	157	3
✅ nitro-node	132	28
✅ nitro-quickjs	132	28
✅ nuxt-node	132	28
✅ nuxt-quickjs	132	28
✅ python-node	66	94
✅ sveltekit-node	151	9
✅ sveltekit-quickjs	151	9
✅ tanstack-start-node	132	28
✅ tanstack-start-quickjs	132	28
✅ vite-node	132	28
✅ vite-quickjs	132	28

✅ 💻 Local Development

App	Passed	Skipped
✅ astro-stable-node	134	26
✅ astro-stable-quickjs	134	26
✅ express-stable-node	134	26
✅ express-stable-quickjs	134	26
✅ fastify-stable-node	134	26
✅ fastify-stable-quickjs	134	26
✅ hono-stable-node	134	26
✅ hono-stable-quickjs	134	26
✅ nest-stable-node	134	26
✅ nest-stable-quickjs	134	26
✅ nextjs-turbopack-canary-node	141	19
✅ nextjs-turbopack-canary-quickjs	141	19
✅ nextjs-turbopack-stable-node	160	0
✅ nextjs-turbopack-stable-quickjs	160	0
✅ nextjs-webpack-canary-node	141	19
✅ nextjs-webpack-canary-quickjs	141	19
✅ nextjs-webpack-stable-node	160	0
✅ nextjs-webpack-stable-quickjs	160	0
✅ nitro-stable-node	134	26
✅ nitro-stable-quickjs	134	26
✅ nuxt-stable-node	134	26
✅ nuxt-stable-quickjs	134	26
✅ sveltekit-stable-node	153	7
✅ sveltekit-stable-quickjs	153	7
✅ tanstack-start-node	134	26
✅ tanstack-start-quickjs	134	26
✅ vite-stable-node	134	26
✅ vite-stable-quickjs	134	26

✅ 📦 Local Production

App	Passed	Skipped
✅ astro-stable-node	134	26
✅ astro-stable-quickjs	134	26
✅ express-stable-node	134	26
✅ express-stable-quickjs	134	26
✅ fastify-stable-node	134	26
✅ fastify-stable-quickjs	134	26
✅ hono-stable-node	134	26
✅ hono-stable-quickjs	134	26
✅ nest-stable-node	134	26
✅ nest-stable-quickjs	134	26
✅ nextjs-turbopack-canary-node	141	19
✅ nextjs-turbopack-canary-quickjs	141	19
✅ nextjs-turbopack-stable-node	160	0
✅ nextjs-turbopack-stable-quickjs	160	0
✅ nextjs-webpack-canary-node	141	19
✅ nextjs-webpack-canary-quickjs	141	19
✅ nextjs-webpack-stable-node	160	0
✅ nextjs-webpack-stable-quickjs	160	0
✅ nitro-stable-node	134	26
✅ nitro-stable-quickjs	134	26
✅ nuxt-stable-node	134	26
✅ nuxt-stable-quickjs	134	26
✅ sveltekit-stable-node	153	7
✅ sveltekit-stable-quickjs	153	7
✅ tanstack-start-node	134	26
✅ tanstack-start-quickjs	134	26
✅ vite-stable-node	134	26
✅ vite-stable-quickjs	134	26

✅ 🐘 Local Postgres

App	Passed	Skipped
✅ astro-stable-node	134	26
✅ astro-stable-quickjs	134	26
✅ express-stable-node	134	26
✅ express-stable-quickjs	134	26
✅ fastify-stable-node	134	26
✅ fastify-stable-quickjs	134	26
✅ hono-stable-node	134	26
✅ hono-stable-quickjs	134	26
✅ nest-stable-node	134	26
✅ nest-stable-quickjs	134	26
✅ nextjs-turbopack-canary-node	141	19
✅ nextjs-turbopack-canary-quickjs	141	19
✅ nextjs-turbopack-stable-node	160	0
✅ nextjs-turbopack-stable-quickjs	160	0
✅ nextjs-webpack-canary-node	141	19
✅ nextjs-webpack-canary-quickjs	141	19
✅ nextjs-webpack-stable-node	160	0
✅ nextjs-webpack-stable-quickjs	160	0
✅ nitro-stable-node	134	26
✅ nitro-stable-quickjs	134	26
✅ nuxt-stable-node	134	26
✅ nuxt-stable-quickjs	134	26
✅ sveltekit-stable-node	153	7
✅ sveltekit-stable-quickjs	153	7
✅ tanstack-start-node	134	26
✅ tanstack-start-quickjs	134	26
✅ vite-stable-node	134	26
✅ vite-stable-quickjs	134	26

✅ 🪟 Windows

App	Passed	Failed	Skipped
✅ nextjs-turbopack-node	160	0	0
✅ nextjs-turbopack-quickjs	160	0	0

✅ 🌐 Cross-language Conformance

App	Passed	Failed	Skipped
✅ python	68	0	73

✅ vercel-http-transport

App	Passed	Skipped
✅ example	132	28
✅ express	132	28
✅ hono	132	28
✅ nextjs-turbopack	157	3
✅ nitro	132	28
✅ vite	132	28

✅ vercel-multi-region

App	Passed	Failed	Skipped
✅ nextjs-turbopack	27	0	0

✅ vercel-ws-transport

App	Passed	Skipped
✅ example	132	28
✅ express	132	28
✅ nextjs-turbopack	157	3
✅ vite	132	28

📋 View full workflow run

github-actions · 2026-09-04T20:47:50Z

📊 Workflow Benchmarks

commit b89b982 · Fri, 04 Sep 2026 21:25:30 GMT · run logs

Backend: vercel · app: nextjs-turbopack

Metric	Scenario	Best (ms)	P75 (ms)	P90 (ms)	P99 (ms)	Samples
TTFS	step	196 (-74%) 💚	1272 🔴 (+20%) 🔻	1293 🔴 (+15%) 🔻	1403 🔴 (+1.6%)	30
TTFS	stream	214 (-78%) 💚	1344 🔴 (+31%) 🔻	1353 🔴 (+29%) 🔻	1447 🔴 (+34%) 🔻	30
TTFS	hook + stream	453 (-63%) 💚	1546 🔴 (+11%)	1584 🔴 (+6.0%)	5758 🔴 (+197%) 🔻	30
Fan-out TTFS	Promise.all(100 steps)	589	1787	2009	2078	10
Fan-out TTLS	Promise.all(100 steps)	1883	3346	3943	8394	10
STSO	1020 steps (inline)	109	137	158	223	1019
WO	1020 steps	136220 (-65%) 💚	136220 (-65%) 💚	136220 (-65%) 💚	136220 (-65%) 💚	1
CRTT	first chunk (pooled)	61	106	134	173	28

Streams

Scenario	CRTT 1st	p75	p90	p99	CDV max	iters
paced control (100/s, 60B)	91.5	155	221	361	164	10
size sweep (100/s, 160B-12KB)	85	198	410	663	254	10
replay gateway-gpt-5.4-nano-2000t (1x)	89	167	1817	3998	375	3
replay eve-gpt-5.6-sol-2000t (1x)	82	142	200	427	340	2
replay eve-gpt-5.6-sol-2000t (2x)	88	179	270	590	326	3

📈 STSO distribution (inline / queue-hop histograms)

1020 steps (inline)

Cumulative STSO time: 136078ms over 1019 samples

_{No main baseline with raw samples yet — showing this run's distribution on its own; the diff appears once a run on main has recorded them.}

100-150 ms  ████████████████████████  steps 862
150-200 ms  ████                      steps 141
200-250 ms  █                         steps  13
250-300 ms  █                         steps   1
300-350 ms  █                         steps   1
700-750 ms  █                         steps   1

📈 CRTT drill-down (RTT distributions & profiles)

_{No main baseline yet — percentages appear once a run on main has recorded CRTT.}

variant  RTT 1ms→5s+      avg  p50   p90   p99     n
control  ······▃█▁····  132.2  121   221   361  3000
sweep    ······▃█▂▁···  154.6  122   410   663  3000
gw 1x    ·····▁▆█▁▁▁▁·  232.5  107  1817  3998  5295
eve 1x   ·····▁▆█▂▁···  121.5  105   200   427  5186
eve 2x   ·····▁▃█▂▁···  153.6  129   270   590  7779

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

control  █▅▅▃▄▁▃▄█▃  111–156ms
sweep    ▅▇▇▅▂▅█▄▁▂  127–182ms
gw 1x    ▁▁▆█▂▁▁▁▁▁  98–778ms
eve 1x   ▃█▇▄▁▇▄█▂▄  105–136ms
eve 2x   ▁▂▁▁▁▅▅█▅▃  119–220ms

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

sweep  ▁▃▅▆█▅▂  151–159ms

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

control  ▄▅▁▂▃▁▅▄█▄  35–49ms
sweep    ▁▅▇▄▆█▄▂▄▃  38–76ms
gw 1x    ▃▃█▂▂▂▃▂▁▂  27–71ms
eve 1x   ▁█▄▂▂▂▃▂▁▆  21–32ms
eve 2x   ▄▇▃▃▅██▁▅▇  18–28ms

ℹ️ 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 · 2026-09-04T20:51:27Z

Sim World

Simulated world deterministic testing for races. Traces

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

fence=per-spec

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

Full trace: world-sim.txt

github-actions · 2026-09-04T20:52:08Z

Framework	Flow route	Step reg.	Framework output
hono	201.6 KiB (±0)	41.4 KiB (+656 B)	1.77 MiB (+938 B)
nextjs-turbopack	207.0 KiB (±0)	439 B (±0)	768.9 KiB (+158 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.

b89b982 · run

Hydrating a hook's metadata is a decrypting READ: it needs the owning run's payload keys, and resolving those costs a run fetch plus a `run-key` API round trip (~350ms). `getHookByToken()` did that work eagerly on every lookup that found a metadata-bearing hook, so callers that only wanted `runId`/`token` — and hook resumption, which never reads metadata at all — paid for it anyway. `metadata` is now a getter returning a memoized Promise, the same shape as `run.returnValue`. The lookup is one read again; hydration and the key resolution behind it happen on first access, or never. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-Authored-By: Pranay Prakash <1797812+pranaygp@users.noreply.github.com>

pranaygp requested a review from a team as a code owner September 4, 2026 20:31

Copilot AI lite review requested due to automatic review settings September 4, 2026 20:31

vercel Bot deployed to Preview – workbench-python-workflow September 4, 2026 20:31 View deployment

Copilot started reviewing on behalf of pranaygp September 4, 2026 20:31 View session

vercel Bot deployed to Preview – workflow-web September 4, 2026 20:32 View deployment

vercel Bot deployed to Preview – workbench-nitro-workflow September 4, 2026 20:33 View deployment

vercel Bot deployed to Preview – workflow-tarballs September 4, 2026 20:33 View deployment

vercel Bot deployed to Preview – workbench-nestjs-workflow September 4, 2026 20:33 View deployment

vercel Bot deployed to Preview – workbench-hono-workflow September 4, 2026 20:33 View deployment

vercel Bot deployed to Preview – workbench-fastify-workflow September 4, 2026 20:33 View deployment

vercel Bot deployed to Preview – workbench-astro-workflow September 4, 2026 20:33 View deployment

vercel Bot deployed to Preview – workbench-express-workflow September 4, 2026 20:33 View deployment

vercel Bot deployed to Preview – workbench-vite-workflow September 4, 2026 20:33 View deployment

vercel Bot deployed to Preview – example-workflow September 4, 2026 20:33 View deployment

vercel Bot deployed to Preview – workbench-tanstack-start-workflow September 4, 2026 20:33 View deployment

vercel Bot deployed to Preview – workbench-sveltekit-workflow September 4, 2026 20:33 View deployment

vercel Bot deployed to Preview – example-nextjs-workflow-webpack September 4, 2026 20:33 View deployment

vercel Bot deployed to Preview – workbench-nuxt-workflow September 4, 2026 20:33 View deployment

vercel Bot deployed to Preview – example-nextjs-workflow-turbopack September 4, 2026 20:33 View deployment

vercel Bot deployed to Preview – workflow-docs September 4, 2026 20:34 View deployment

Copilot AI reviewed Sep 4, 2026

View reviewed changes

Comment thread packages/core/src/runtime/resume-hook.ts

* The hook's user-defined metadata, hydrated on first access and memoized.

* Resolves `undefined` when the hook carries no metadata.

*/

readonly metadata: Promise<unknown>;

vercel Bot deployed to Preview – workflow-swc-playground September 4, 2026 20:36 View deployment

pranaygp force-pushed the lazy-hook-metadata-getter branch from a8c1496 to 08b694a Compare September 4, 2026 20:47

vercel Bot deployed to Preview – workbench-python-workflow September 4, 2026 20:48 View deployment

vercel Bot deployed to Preview – workflow-web September 4, 2026 20:49 View deployment

vercel Bot deployed to Preview – workbench-nestjs-workflow September 4, 2026 20:49 View deployment

vercel Bot deployed to Preview – workbench-vite-workflow September 4, 2026 20:50 View deployment

vercel Bot deployed to Preview – workbench-sveltekit-workflow September 4, 2026 20:50 View deployment

vercel Bot deployed to Preview – workbench-nuxt-workflow September 4, 2026 20:50 View deployment

vercel Bot deployed to Preview – workbench-tanstack-start-workflow September 4, 2026 20:50 View deployment

vercel Bot deployed to Preview – example-nextjs-workflow-turbopack September 4, 2026 20:50 View deployment

vercel Bot deployed to Preview – example-nextjs-workflow-webpack September 4, 2026 20:50 View deployment

vercel Bot deployed to Preview – workflow-docs September 4, 2026 20:51 View deployment

vercel Bot deployed to Preview – workflow-swc-playground September 4, 2026 20:52 View deployment

pranaygp force-pushed the lazy-hook-metadata-getter branch from 08b694a to b89b982 Compare September 4, 2026 21:01

vercel Bot deployed to Preview – workbench-python-workflow September 4, 2026 21:01 View deployment

vercel Bot deployed to Preview – workflow-web September 4, 2026 21:02 View deployment

vercel Bot deployed to Preview – workbench-hono-workflow September 4, 2026 21:02 View deployment

vercel Bot deployed to Preview – workflow-tarballs September 4, 2026 21:02 View deployment

vercel Bot deployed to Preview – workbench-nestjs-workflow September 4, 2026 21:02 View deployment

vercel Bot deployed to Preview – workbench-nitro-workflow September 4, 2026 21:02 View deployment

vercel Bot deployed to Preview – workbench-vite-workflow September 4, 2026 21:02 View deployment

vercel Bot deployed to Preview – workbench-fastify-workflow September 4, 2026 21:02 View deployment

vercel Bot deployed to Preview – workbench-astro-workflow September 4, 2026 21:02 View deployment

vercel Bot deployed to Preview – example-workflow September 4, 2026 21:02 View deployment

vercel Bot deployed to Preview – workbench-express-workflow September 4, 2026 21:02 View deployment

vercel Bot deployed to Preview – workbench-tanstack-start-workflow September 4, 2026 21:02 View deployment

vercel Bot deployed to Preview – workbench-sveltekit-workflow September 4, 2026 21:02 View deployment

vercel Bot deployed to Preview – workbench-nuxt-workflow September 4, 2026 21:02 View deployment

vercel Bot deployed to Preview – example-nextjs-workflow-turbopack September 4, 2026 21:02 View deployment

vercel Bot deployed to Preview – example-nextjs-workflow-webpack September 4, 2026 21:02 View deployment

vercel Bot deployed to Preview – workflow-docs September 4, 2026 21:03 View deployment

vercel Bot deployed to Preview – workflow-swc-playground September 4, 2026 21:05 View deployment

Navigation Menu

Uh oh!

[core] Make `hook.metadata` a lazy Promise getter - #3988

[core] Make `hook.metadata` a lazy Promise getter#3988
pranaygp wants to merge 1 commit into
mainfrom
lazy-hook-metadata-getter

pranaygp commented Sep 4, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Sep 4, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Sep 4, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

github-actions Bot commented Sep 4, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Sep 4, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Sep 4, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Sep 4, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

pranaygp commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary & Motivation

What changed

Breaking change

Test Plan

Docs Preview

Uh oh!

changeset-bot Bot commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel Bot commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

github-actions Bot commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🧪 E2E Test Results

⚠️ Flaky E2E Tests (passed on retry)

🛠 Infra Events (absorbed by the harness)

E2E Test Summary

Uh oh!

github-actions Bot commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📊 Workflow Benchmarks

Uh oh!

github-actions Bot commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Sim World

Uh oh!

github-actions Bot commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

pranaygp commented Sep 4, 2026 •

edited

Loading

changeset-bot Bot commented Sep 4, 2026 •

edited

Loading

vercel Bot commented Sep 4, 2026 •

edited

Loading

github-actions Bot commented Sep 4, 2026 •

edited

Loading

github-actions Bot commented Sep 4, 2026 •

edited

Loading

github-actions Bot commented Sep 4, 2026 •

edited

Loading

github-actions Bot commented Sep 4, 2026 •

edited

Loading