Uh oh!
There was an error while loading. Please reload this page.
docs: document run idempotency - #2011
Merged
Merged
Conversation
Contributor
🦋 Changeset detectedLatest commit: bd22586 The changes in this PR will be included in the next version bump. This PR includes changesets to release 0 packagesWhen changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types 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 |
Contributor
🧪 E2E Test Results✅ All tests passed Summary
Details by Category✅ ▲ Vercel Production
✅ 💻 Local Development
✅ 📦 Local Production
✅ 🐘 Local Postgres
✅ 🪟 Windows
✅ 📋 Other
❌ Some E2E test jobs failed:
Check the workflow run for details. |
Contributor
📊 Benchmark Results
workflow with no steps💻 Local Development
▲ Production (Vercel)
workflow with 1 step💻 Local Development
▲ Production (Vercel)
workflow with 10 sequential steps💻 Local Development
▲ Production (Vercel)
workflow with 25 sequential steps💻 Local Development
▲ Production (Vercel)
workflow with 50 sequential steps💻 Local Development
▲ Production (Vercel)
Promise.all with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
Promise.all with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
Promise.all with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
Promise.race with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
Promise.race with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
Promise.race with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
workflow with 10 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
workflow with 25 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
workflow with 50 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
workflow with 10 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
workflow with 25 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
workflow with 50 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
Stream Benchmarks(includes TTFB metrics)workflow with stream💻 Local Development
▲ Production (Vercel)
stream pipeline with 5 transform steps (1MB)💻 Local Development
▲ Production (Vercel)
10 parallel streams (1MB each)💻 Local Development
▲ Production (Vercel)
fan-out fan-in 10 streams (1MB each)💻 Local Development
▲ Production (Vercel)
SummaryFastest Framework by WorldWinner determined by most benchmark wins
Fastest World by FrameworkWinner determined by most benchmark wins
Column Definitions
Worlds:
❌ Some benchmark jobs failed:
Check the workflow run for details. |
pranaygp
commented
May 18, 2026
Uh oh!
There was an error while loading. Please reload this page.
pranaygp
commented
May 18, 2026
Uh oh!
There was an error while loading. Please reload this page.
pranaygp
commented
May 18, 2026
Uh oh!
There was an error while loading. Please reload this page.
pranaygp
commented
May 18, 2026
Uh oh!
There was an error while loading. Please reload this page.
pranaygp
commented
May 18, 2026
Uh oh!
There was an error while loading. Please reload this page.
pranaygp
commented
May 18, 2026
Uh oh!
There was an error while loading. Please reload this page.
…docs-run-idempotency * origin-https/main: (115 commits) [core] V2: unify wait+step queue dispatch in suspension processing (#1925) fix(world-local,world-postgres): make duplicate hook_created idempotent (#2295) docs(observability): remove MVP implementation detail bullet (#2367) fix: settle aborted parallel steps before completing abortParallelWorkflow (#2244) Add native v4 workflow attribute events (#2226) Version Packages (beta) (#2326) [ci] Fix flaky windows unit tests (#2359) Capture Vercel runtime logs when e2e Vercel Prod lanes fail (#2356) Fix e2e failure reporting under vitest 4 and preserve fetch error causes (#2355) [core] Fix process crash from rejected waitUntil promises (#2336) [core] Remove duplicate `waitUntil` for suspension handler async operations (#2345) Prevent local tests from hanging (#2338) feat(core): add optional namespace for queue topic prefix (#2305) [web-shared] Show precise durations in the new trace viewer (#2335) Validate unique workflow step IDs at build time (#2018) Move run attributes into their own detail card (#2327) [core] Forward-port stream reconnect to getReadable level (#2318) [docs] Add "Step executed multiple times" error page (#2310) Fix flickering on the detail panel when navigating the trace viewer (#2325) Version Packages (beta) (#2254) ... # Conflicts: # docs/content/docs/v4/cookbook/advanced/child-workflows.mdx # docs/content/docs/v5/cookbook/advanced/child-workflows.mdx # docs/content/docs/v5/cookbook/agent-patterns/durable-agent.mdx
… into pranaygp/codex/docs-run-idempotency * origin-https/pranaygp/codex/hook-ready: docs: restore SWC Plugin heading in AGENTS.md docs: require docs preview links in PR descriptions for docs changes docs: fix inconsistent hasConflict bullet in create-webhook reference feat: replace hook.ready with hook.hasConflict (Promise<boolean>) test: cover hook ready continuation scheduling feat: add hook ready promise # Conflicts: # docs/content/docs/v4/api-reference/workflow/create-hook.mdx # docs/content/docs/v5/api-reference/workflow/create-hook.mdx
- Primary claim pattern is now `if (await hook.hasConflict)` instead of try/catch on HookConflictError; payload awaits still reject with HookConflictError (with conflictingRunId) when the owner's run ID is needed. - Route example returns the active owner via resumeHook()'s runId instead of threading conflictingRunId through the workflow result. - Update claim-pattern prose across start(), getHookByToken(), world storage, scheduling, workflow composition, and cookbook idempotency pages (v4 + v5). - Add @skip-typecheck marker to the cross-block route sample, fixing a pre-existing docs typecheck failure. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The early callout was too vague and out of place at the top of the API reference. Replace it with a 'Resume or Start' example section that explains the flow, shows the resume-first/start-then-retry route, and links to the run idempotency pattern. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…f awaiting returnValue The 'Resume or Start' example returned the just-started run's runId with reused: false even when a concurrent request's run won the token race — the payload had reached the actual owner, so the response pointed callers at a run that exits as a duplicate. The foundations route handled the race correctly but by awaiting run.returnValue, blocking the HTTP response on full workflow completion. resumeHook() always resolves against the actual active owner, so comparing the resumed hook's runId with the started run's runId detects the race in both examples — race-correct and non-blocking.
TooTallNate
approved these changes
Jun 11, 2026
TooTallNate
left a comment
Member
There was a problem hiding this comment.
Approve — accurate, well-hedged docs; synced to main and one pattern defect fixed in-branch
Now that #2015 is on main, I merged main into this branch (resolving the create-hook.mdx conflicts in favor of this PR's run-idempotency callout) — the diff is down to docs-only (38 files + the empty changeset), exactly as the PR description promised. pnpm test:docs passes (923 samples typechecked).
Technical accuracy — verified against the code
The route samples in the foundations page carry @skip-typecheck (cross-block dependency), so CI doesn't validate them; I checked the API claims manually:
start(processOrder, [orderId])matches the(workflow, args: TArgs, options?)overload returningPromise<Run<TResult>>✓HookNotFoundErroris exported from theworkflow/errorssubpath (./errors→dist/internal/errors.js) ✓resumeHook(token, payload)returnsPromise<Hook>carrying the owner'srunId✓- The
conflictingRunId-on-HookConflictErrorclaim matches #2012 (and its stable backport #2016), so it's accurate for both the v4 and v5 pages ✓ hasConflictsemantics (registration committed on suspension; resolvestrue/false; payload await still rejects withHookConflictError) match the implementation that just landed in #2015 ✓
What I particularly like: the docs are honest about the limits. getHookByToken() is consistently described as an advisory pre-check, the start()-vs-hook-registration race is named explicitly everywhere it matters, the resolution is correctly placed inside the workflow via hook.hasConflict, and the "native atomic start-and-hook API is in the works" framing sets expectations without overpromising. The foundations page carries the full pattern once, and the ~20 cross-link callouts are scoped summaries pointing back at it rather than divergent copies.
One defect fixed in-branch (42d5533) — please review the change
The two route examples disagreed on race handling, and one was wrong:
resume-hook.mdx"Resume or Start" returned{ runId: run.runId, reused: false }afterstart()+resumeWithRetry()— but when a concurrent request's run wins the token race, the resume reaches that owner, and this response points the caller at a run that exits as a duplicate without doing any work. Wrong answer in exactly the race case the section teaches about.foundations/idempotency.mdxhandled the race correctly but viaawait run.returnValue, which blocks the HTTP response on full workflow completion (hook resume +chargeOrder+ every step). That's an anti-pattern for a copy-paste route sample — workflows are long-lived by design.
Both are fixed by one observation: resumeHook() always resolves against the actual active owner, so resumed.runId !== run.runId detects the race — race-correct, non-blocking, and the same shape in both examples. The warn callout's wording is updated to match. Happy to revert if you prefer the returnValue approach for pedagogical reasons, but I'd argue the runId comparison is also the better teaching: it makes "the resume reaches the owner" concrete.
Non-blocking notes
- The 500ms retry budget (
5 × 100ms) inresumeWithRetry/resumeOrderis tight against real cold starts + queue dispatch latency. Worth either a more forgiving schedule (e.g. exponential up to ~5s) or a sentence on the failure consequence: if the retries exhaust afterstart()succeeded, the new run is left suspended awaiting a payload that never arrives (until run timeout). Right now the thrown error reads as transient but leaves a dangling run behind. - v4 docs sequencing, again:
hasConflictis still not onstable(no backport PR exists yet), and this PR widens the v4-docs-reality gap from one page (#2015) to roughly twenty. Same deliberate-choice ask as before — either the #2015 backport + 4.x release should follow promptly, or the v4 halves of these pages should wait for it. The content itself is version-accurate; it's purely a shipping-order question. - The cookbook's minimal
getHookByToken()-then-start()example intentionally omits the resume-retry mechanics — good scoping, and the pointer to foundations for "the full pattern" covers it.
CI
All checks green or pending on the synced head; mergeable: MERGEABLE. The branch now contains the merge of main (e6f0516de) plus the race-handling fix (42d5533d4).
…ull>)
hasConflict's boolean didn't expose WHICH run owns the token, so the
duplicate run couldn't act on the conflict. getConflict resolves with
null once registration commits, or with a Run handle for the conflicting
run — letting the workflow return/log the owner's runId, inspect its
status, await its result, or cancel it and continue, all in code.
The workflow-mode create-hook module exposes the bundle's compiled Run
class (durable step-proxy methods) on a well-known symbol so the host-
side hook consumer can construct the conflicting run inside the VM.
Contexts without the class (plain unit tests) fall back to a { runId }
object, which is also the documented v4 shape (no native Run
serialization in v4).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>…n-idempotency * pranaygp/hook-get-conflict: feat: replace hook.hasConflict with hook.getConflict (Promise<Run | null>)
Run idempotency docs now use getConflict (resolves with the conflicting
Run in v5, { runId } in v4) and document code-driven conflict strategies
in place of static ID-reuse policies: reject the duplicate, adopt the
owner's result, inspect before deciding, signal the owner via
resumeHook, and supersede via cancel-and-reclaim.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>…empotency' into pranaygp/codex/docs-run-idempotency * origin-https/pranaygp/codex/docs-run-idempotency: docs: detect the concurrent-start race via runId comparison instead of awaiting returnValue # Conflicts: # docs/content/docs/v4/foundations/idempotency.mdx # docs/content/docs/v5/foundations/idempotency.mdx
getConflict's contract is Promise<Run | null>. In the degenerate cases
where a real Run cannot be constructed — a hook_conflict event persisted
by an old world without conflictingRunId, or a context that never loaded
the workflow-mode create-hook module — reject with HookConflictError
instead of resolving with a { runId }-shaped impostor.
Test harnesses now register the Run class on the (VM) globalThis like
real bundles do.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>A property getter that triggers registration/suspension reads as passive state; a method makes the side effect explicit. Update implementation, types, tests, e2e workflows, docs, and changeset. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…n-idempotency * pranaygp/hook-get-conflict: refactor: make getConflict a method — hook.getConflict() fix: never resolve getConflict with a non-Run fallback shape
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Route examples typecheck as-is since the runId-comparison rewrite; strategy fragments are now complete self-contained workflows; the publishing-libraries cross-block dependency uses the declare @setup convention. 934 samples typechecked, none skipped by this PR. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Only register WORKFLOW_RUN_CLASS when the workflow runtime is present (WORKFLOW_CREATE_HOOK installed on globalThis), so host imports of the workflow-mode module neither mutate the host global nor expose the non-step-proxy host Run. - Drop #run-idempotency link fragments — that section lands in the stacked docs PR (#2011), which restores the anchored links. - Note in docs that getConflict() rejects with HookConflictError for legacy hook_conflict events lacking the owner's run ID. - Changeset now calls out the hasConflict -> getConflict() replacement. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…n-idempotency * pranaygp/hook-get-conflict: review: guard Run class registration, fix anchors, clarify changeset
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…her systems Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
TooTallNate
approved these changes
Jun 12, 2026
TooTallNate
left a comment
Member
There was a problem hiding this comment.
Approve — re-reviewed after the getConflict() migration; synced to main again
Re-review following #2373's merge (which replaced hook.hasConflict with hook.getConflict() returning Run | null). I merged main into this branch once more (45fe1a585): the core-package conflicts were the branch's embedded pre-merge copy of #2373 versus the landed version (resolved by taking main wholesale, which includes the registry refactor), and the four docs conflicts were this PR's anchored links + callouts versus #2373's baseline pages (resolved by keeping this PR's superset). The effective diff is docs-only + the empty changeset, and pnpm test:docs passes — now at 1012 typechecked samples with zero @skip-typecheck escape hatches, since the route samples were restructured to typecheck standalone. That closes the "flagship sample isn't CI-validated" gap from my first review.
The getConflict() migration is done right
- Zero stale
hasConflictreferences anywhere in the PR. - The run-idempotency pattern now returns
{ status: "duplicate", runId: conflict.runId }— the duplicate run can finally say who owns the token, which is what makes the route example's dedupe response meaningful. - The new Conflict-handling strategies section is the best part of this revision. All five strategies are technically sound — I audited each against the implementation:
- Reject:
conflict.runIdplain property, deterministic ✓ - Adopt:
await conflict.returnValuedurable step accessor ✓ - Inspect:
await conflict.status✓ - Signal:
resumeHook()correctly wrapped in a"use step"function (API calls can't run in workflow context) ✓ - Supersede:
await conflict.cancel()+ retry loop creating a fresh hook per attempt, correctly handling the disposal-propagation window; per-iterationusingdisposal of conflicted hooks is safe (pinned by the #2015 test) ✓
- Reject:
- The "no policy enum — policy is ordinary code" framing (now phrased generically without naming other systems) is a genuinely good product argument, and the inspect-before-deciding strategy demonstrates exactly what static configuration can't express.
- The v4/v5 split is version-accurate: v4 documents the
{ runId }resolution withgetRun(conflict.runId)inside steps (no nativeRunconstruction in 4.x workflow context); v5 documents theRunhandle with durable accessors. The older-world degenerate case (hook_conflictwithoutconflictingRunId→ rejects withHookConflictError) is documented in the hooks foundations page. - My earlier race-handling fix (
reused: resumed.runId !== run.runId) survived the revision and the warn callout's wording is consistent with it.
Two non-blocking notes
- The inspect strategy's terminal-state fall-through is slightly loose: when the owner is already terminal, the example proceeds to
processOwnedOrder()without holding the token (this run's hook already recorded its conflict; the released token isn't retroactively claimed). A third concurrent run could claim it meanwhile. The supersede example handles this properly with its fresh-hook retry loop — a one-line pointer ("to do the work while holding the token after the owner ends, use the supersede pattern's retry loop") would prevent copy-paste of the loose version into duplicate-sensitive code. - The recurring v4 sequencing flag, final form: the v4 pages now document
getConflict()— an API that has never existed in any 4.x release (hasConflictdidn't ship there either). The documented-but-unreleased v4 surface keeps compounding across #2015 → #2373 → this PR. None of it is wrong — the v4 content correctly describes what a backport would look like — but the backport chain (now effectively just #2373, since it subsumes #2015's API) should land in a 4.x release soon after this merges, or the v4 docs are fiction in the meantime.
Everything else from my first review stands. Nice iteration — the strategies section turned a reference page into an actual design guide.
…docs-run-idempotency * origin-https/main: test: e2e coverage for run-idempotency conflict-handling strategies (#2387) fix(docs): repair broken links, fix the link linter, and version-correct v5 Card + edit links (#2391) feat(web-shared): RelativeTimeCard with shared ContextCard provider (#2328) Add allowReservedAttributes option to start() (#2385) # Conflicts: # docs/content/docs/v4/cookbook/common-patterns/idempotency.mdx # docs/content/docs/v5/cookbook/common-patterns/idempotency.mdx
Contributor
Backport PR opened against |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
start()currently creates a new run for each call and does not accept an idempotency keyhook.getConflict()(Addhook.hasConflictfor early hook conflict detection #2015, revised by Replace hook.hasConflict with hook.getConflict() returning the conflicting Run #2373): the workflow creates a hook with a domain-derived token and checksconst conflict = await hook.getConflict()before duplicate-sensitive work — awaitinggetConflict()suspends the workflow to commit the hook registration and resolves with the conflictingRun(v5) /{ runId }(v4) when another active run owns the token, ornullonce registeredconflict.returnValue, inspectconflict.statusbefore deciding, signal the owner viaresumeHook()from a step, or supersede it viaconflict.cancel()and re-claim the tokenstart(),getRun(), hook APIs, workflowfetch(), child workflows, session integrations, scheduling, timeouts, and publishing-library examplesNote
Stacked on #2373 (
hook.getConflict(), the follow-up to the merged #2015): this PR's base is that branch, so the diff here is the idempotency docs only. Merge #2373 first — GitHub will retarget this PR tomainautomatically.Notes
start()when duplicate run creation is unsafe.getHookByToken()) is documented as an advisory pre-check, not atomic enough to replace run idempotency; the race is resolved inside the workflow viahook.getConflict().resumeHook()'srunIdagainst the started run'srunId— race-correct without blocking on workflow completion.Docs Preview
Changed pages on the docs preview deployment:
start()API referencegetHookByToken()API referencegetRun()API referenceresumeHook()API referencecreateHook()API referencefetch()API referenceSmaller idempotency cross-link callouts were also added to the scheduling, timeouts, workflow composition, child workflows, publishing libraries, AI SDK, Chat SDK, and Sandbox cookbook pages (same paths under
/v5/docsfor v5).Validation
pnpm test:docs(921 samples typechecked, 2 files) — also fixed a pre-existing failure in the run-idempotency route sample with a@skip-typecheckcross-block markergit diff --check