docs: document run idempotency#2011
Draft
pranaygp wants to merge 15 commits into
Draft
Conversation
Contributor
🦋 Changeset detectedLatest commit: 099876b 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❌ Some tests failed Summary
❌ Failed Tests▲ Vercel Production (4 failed)example (1 failed):
nitro (1 failed):
nuxt (1 failed):
sveltekit (1 failed):
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
workflow with 1 step💻 Local Development
workflow with 10 sequential steps💻 Local Development
workflow with 25 sequential steps💻 Local Development
workflow with 50 sequential steps💻 Local Development
Promise.all with 10 concurrent steps💻 Local Development
Promise.all with 25 concurrent steps💻 Local Development
Promise.all with 50 concurrent steps💻 Local Development
Promise.race with 10 concurrent steps💻 Local Development
Promise.race with 25 concurrent steps💻 Local Development
Promise.race with 50 concurrent steps💻 Local Development
workflow with 10 sequential data payload steps (10KB)💻 Local Development
workflow with 25 sequential data payload steps (10KB)💻 Local Development
workflow with 50 sequential data payload steps (10KB)💻 Local Development
workflow with 10 concurrent data payload steps (10KB)💻 Local Development
workflow with 25 concurrent data payload steps (10KB)💻 Local Development
workflow with 50 concurrent data payload steps (10KB)💻 Local Development
Stream Benchmarks (includes TTFB metrics)workflow with stream💻 Local Development
stream pipeline with 5 transform steps (1MB)💻 Local Development
10 parallel streams (1MB each)💻 Local Development
fan-out fan-in 10 streams (1MB each)💻 Local Development
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
pranaygp
commented
May 18, 2026
pranaygp
commented
May 18, 2026
pranaygp
commented
May 18, 2026
pranaygp
commented
May 18, 2026
pranaygp
commented
May 18, 2026
Contributor
There was a problem hiding this comment.
Pull request overview
This PR expands v4 and v5 documentation around idempotency, especially how duplicate workflow starts relate to start(), hooks, and application-level coordination.
Changes:
- Adds run-idempotency guidance to foundations and cookbook pages.
- Adds API reference callouts and related links for
start(), hooks,getRun(), and workflowfetch(). - Mirrors the updates across v4 and v5 docs.
Reviewed changes
Copilot reviewed 38 out of 38 changed files in this pull request and generated 20 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/content/docs/v5/foundations/idempotency.mdx | Expands conceptual idempotency guidance. |
| docs/content/docs/v5/cookbook/integrations/sandbox.mdx | Adds /start idempotency notes. |
| docs/content/docs/v5/cookbook/integrations/chat-sdk.mdx | Adds first-message routing guidance. |
| docs/content/docs/v5/cookbook/integrations/ai-sdk.mdx | Adds first-turn idempotency guidance. |
| docs/content/docs/v5/cookbook/index.mdx | Updates idempotency summary text. |
| docs/content/docs/v5/cookbook/common-patterns/workflow-composition.mdx | Adds child-run idempotency callout and links. |
| docs/content/docs/v5/cookbook/common-patterns/timeouts.mdx | Links timeout side effects to idempotency. |
| docs/content/docs/v5/cookbook/common-patterns/scheduling.mdx | Adds scheduled-run idempotency callout. |
| docs/content/docs/v5/cookbook/common-patterns/idempotency.mdx | Reworks cookbook idempotency pattern. |
| docs/content/docs/v5/cookbook/agent-patterns/durable-agent.mdx | Adds agent-start idempotency note. |
| docs/content/docs/v5/cookbook/advanced/publishing-libraries.mdx | Adds idempotency cross-link. |
| docs/content/docs/v5/cookbook/advanced/child-workflows.mdx | Adds related start() link. |
| docs/content/docs/v5/api-reference/workflow/fetch.mdx | Adds mutation/idempotency warning. |
| docs/content/docs/v5/api-reference/workflow/create-hook.mdx | Adds hook-token idempotency callout. |
| docs/content/docs/v5/api-reference/workflow-api/world/storage.mdx | Adds low-level hook lookup guidance. |
| docs/content/docs/v5/api-reference/workflow-api/start.mdx | Documents that each start() call creates a run. |
| docs/content/docs/v5/api-reference/workflow-api/resume-hook.mdx | Adds resume-or-start callout. |
| docs/content/docs/v5/api-reference/workflow-api/get-run.mdx | Clarifies runId vs business-key lookup. |
| docs/content/docs/v5/api-reference/workflow-api/get-hook-by-token.mdx | Adds idempotency-related hook lookup guidance. |
| docs/content/docs/v4/foundations/idempotency.mdx | Mirrors v5 conceptual idempotency updates. |
| docs/content/docs/v4/cookbook/integrations/sandbox.mdx | Mirrors sandbox idempotency notes. |
| docs/content/docs/v4/cookbook/integrations/chat-sdk.mdx | Mirrors chat routing guidance. |
| docs/content/docs/v4/cookbook/integrations/ai-sdk.mdx | Mirrors first-turn guidance. |
| docs/content/docs/v4/cookbook/index.mdx | Mirrors idempotency summary update. |
| docs/content/docs/v4/cookbook/common-patterns/workflow-composition.mdx | Mirrors composition callout and links. |
| docs/content/docs/v4/cookbook/common-patterns/timeouts.mdx | Mirrors timeout/idempotency links. |
| docs/content/docs/v4/cookbook/common-patterns/scheduling.mdx | Mirrors scheduled-run callout. |
| docs/content/docs/v4/cookbook/common-patterns/idempotency.mdx | Mirrors cookbook idempotency rewrite. |
| docs/content/docs/v4/cookbook/agent-patterns/durable-agent.mdx | Mirrors agent-start note. |
| docs/content/docs/v4/cookbook/advanced/publishing-libraries.mdx | Mirrors idempotency cross-link. |
| docs/content/docs/v4/cookbook/advanced/child-workflows.mdx | Mirrors related start() link. |
| docs/content/docs/v4/api-reference/workflow/fetch.mdx | Mirrors fetch warning. |
| docs/content/docs/v4/api-reference/workflow/create-hook.mdx | Mirrors hook-token callout. |
| docs/content/docs/v4/api-reference/workflow-api/world/storage.mdx | Mirrors low-level hook lookup guidance. |
| docs/content/docs/v4/api-reference/workflow-api/start.mdx | Mirrors start() behavior note. |
| docs/content/docs/v4/api-reference/workflow-api/resume-hook.mdx | Mirrors resume-or-start callout. |
| docs/content/docs/v4/api-reference/workflow-api/get-run.mdx | Mirrors runId clarification. |
| docs/content/docs/v4/api-reference/workflow-api/get-hook-by-token.mdx | Mirrors hook lookup guidance. |
Comments suppressed due to low confidence (4)
docs/content/docs/v5/foundations/idempotency.mdx:142
- This first request's
confirmedpayload is dropped when no hook exists yet: the code catchesHookNotFoundError, starts the workflow, and returns without deliveringconfirmedto the newly created hook. If callers do not retry,processOrderWithConfirmationwill wait for a payload that was already received by this route.
docs/content/docs/v4/foundations/idempotency.mdx:142 - This first request's
confirmedpayload is dropped when no hook exists yet: the code catchesHookNotFoundError, starts the workflow, and returns without deliveringconfirmedto the newly created hook. If callers do not retry,processOrderWithConfirmationwill wait for a payload that was already received by this route.
export async function POST(request: Request) {
const { orderId, confirmed } = await request.json();
const token = `order:${orderId}`;
try {
const hook = await resumeHook(token, { confirmed }); // [!code highlight]
return Response.json({ runId: hook.runId, reused: true });
} catch (error) {
if (!HookNotFoundError.is(error)) throw error;
}
const run = await start(processOrderWithConfirmation, [orderId]); // [!code highlight]
return Response.json({ runId: run.runId, reused: false });
docs/content/docs/v5/cookbook/agent-patterns/durable-agent.mdx:131
- Storing the
runIdonly afterstart()returns is too late to prevent concurrent duplicate starts: two retried submissions can both start agent runs before either stores itsrunId. When duplicate run creation is unsafe, the route needs to atomically claim the conversation/request key before callingstart()(or have a recovery path for the extra run).
<Callout type="info">
This route starts a new agent run for each request. If retried submissions should reconnect to the same agent run, store the returned `runId` behind an atomic conversation or request key before returning it. See [Run idempotency](/docs/foundations/idempotency#run-idempotency).
</Callout>
docs/content/docs/v4/cookbook/agent-patterns/durable-agent.mdx:131
- Storing the
runIdonly afterstart()returns is too late to prevent concurrent duplicate starts: two retried submissions can both start agent runs before either stores itsrunId. When duplicate run creation is unsafe, the route needs to atomically claim the conversation/request key before callingstart()(or have a recovery path for the extra run).
<Callout type="info">
This route starts a new agent run for each request. If retried submissions should reconnect to the same agent run, store the returned `runId` behind an atomic conversation or request key before returning it. See [Run idempotency](/docs/foundations/idempotency#run-idempotency).
</Callout>
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
1 task
TooTallNate
reviewed
May 18, 2026
Member
TooTallNate
left a comment
TooTallNate
left a comment
There was a problem hiding this comment.
Comment-only review
Good docs PR. The split between step idempotency (use stepId from getStepMetadata()) and run idempotency (use a deterministic hook token) reads well, and the cross-links from start(), getRun(), getHookByToken(), resumeHook(), create-hook, and the cookbook integrations all point back to the same anchor consistently.
What I verified
- Race-story claim is correct. Walked through the
start()+createHook()timing: requests A and B both observe "no hook" → both callstart()→ both runs eventually reachcreateHook({ token: 'order:X' })→ first to register wins, second getsHookConflictError. The duplicate-run cleanup happens inside the workflow body. ✅ using _idempotency = createHook(...)pattern matches the existing usage inmigrating-from-aws-step-functions.mdx,migrating-from-temporal.mdx,migrating-from-trigger-dev.mdx, andmigrating-from-inngest.mdx. Consistent.- No wording regressions like the "Vercelism" issue in #2010. The new wording is consistent with the rest of the docs.
- v4/v5 content identical — verified with
diff. Reasonable since idempotency semantics didn't change between versions. - All cross-links resolve — the
#run-idempotencyanchor exists in both v4 and v5 idempotency pages.
Inline comments
Two non-blocking observations:
- Missing changeset (same convention as #2010).
- Minor wording suggestion on the race story callout to be slightly more concrete about what's racing.
Otherwise looks good. Once the changeset is added I'd approve. Posting as comment-only to keep the door open for the wording suggestion.
Signed-off-by: Nathan Rajlich <n@n8.io>
Member
|
Pushed an empty changeset directly to the branch (commit 642c898) to unblock the changeset check — figured that was easier than asking you to round-trip on a 2-line file. Otherwise still LGTM from my review above. |
TooTallNate
approved these changes
May 18, 2026
Member
TooTallNate
left a comment
TooTallNate
left a comment
There was a problem hiding this comment.
Changeset is in (pushed 642c898 directly). Approving — the wording suggestion I left earlier is non-blocking.
Contributor
Author
|
Moving this back to draft while we sort out the right run-idempotency API/pattern. One issue with the current hook-token approach: So before this docs PR is ready, we should decide whether Workflow needs a first-class claim/registration primitive, a hook readiness/claim API, or changed |
Contributor
Author
|
Opened the prerequisite runtime/API PR here: #2015 Once that lands, this docs PR should update the idempotency examples to use the new using hook = createHook({ token });
await hook.ready;
// duplicate-sensitive work can run after the hook token is registeredThat avoids requiring consumers to wait for or send hook payload data just to claim the token for run idempotency. In other words, the docs/code examples here should use |
…un-idempotency * origin/main: Expose conflicting run id on hook conflicts (#2012)
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 free
to 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 keystart(),getRun(), hook APIs, workflowfetch(), child workflows, session integrations, scheduling, timeouts, and publishing-library examplesNotes
start()when duplicate run creation is unsafe.Validation
git diff --checkpnpm --filter docs lintcould not run in this worktree becausenode_modulesis missing (biome: command not found); pnpm also warned the current Node is v25.2.1 while the repo supports 18/20/22/24.pnpm test:docscould not run in this worktree becausenode_modulesis missing (vitest: command not found); same Node engine warning.