[docs] Document atomic start Hook admission

[NathanColosimo]

Summary

Document the atomic start(..., { hook }) API, duplicate handling, uncertain start errors, and the contract for World implementers.

This PR is stacked on #3426 and will stay draft until a World implementation is ready.

Docs Preview

Page	Preview
start()	Prevent duplicate starts
Idempotency	Atomic admission
Error overview	workflow/errors
HookConflictError	Reference
WorkflowStartError	Reference
WorkflowWorldError	Reference
World	Capabilities
World storage	events.create()

[changeset-bot]

⚠️ No Changeset found

Latest commit: ce0690c

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
example-nextjs-workflow-turbopack	Ready	Preview	Aug 12, 2026 12:02am
example-nextjs-workflow-webpack	Ready	Preview	Aug 12, 2026 12:02am
example-workflow	Ready	Preview	Aug 12, 2026 12:02am
workbench-astro-workflow	Ready	Preview	Aug 12, 2026 12:02am
workbench-express-workflow	Ready	Preview	Aug 12, 2026 12:02am
workbench-fastify-workflow	Ready	Preview	Aug 12, 2026 12:02am
workbench-hono-workflow	Ready	Preview	Aug 12, 2026 12:02am
workbench-nestjs-workflow	Ready	Preview	Aug 12, 2026 12:02am
workbench-nitro-workflow	Ready	Preview	Aug 12, 2026 12:02am
workbench-nuxt-workflow	Ready	Preview	Aug 12, 2026 12:02am
workbench-python-workflow	Error		Aug 12, 2026 12:02am
workbench-sveltekit-workflow	Ready	Preview	Aug 12, 2026 12:02am
workbench-tanstack-start-workflow	Ready	Preview	Aug 12, 2026 12:02am
workbench-vite-workflow	Ready	Preview	Aug 12, 2026 12:02am
workflow-docs	Ready	Preview, v0	Aug 12, 2026 12:02am
workflow-swc-playground	Ready	Preview	Aug 12, 2026 12:02am
workflow-tarballs	Ready	Preview	Aug 12, 2026 12:02am
workflow-web	Ready	Preview	Aug 12, 2026 12:02am

[vercel]

Additional Suggestion:

isHookTokenClaimReleasable now treats orphaned modern hook token claims (hookId + eventId, missing run) as non-releasable, so their token can never be reclaimed — a regression of the prior "ownerless claim = reclaimable debris" behavior that contradicts the function's own comment.

[github-actions]

Sim World

Simulated world deterministic testing for races. Traces

🟠 Mint-ordered log — 6 fail of 41 total

log=mint-ordered · 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
✅ 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	17	1.0m	MISMATCH	1
❌ stale-read-equal-step-counts	completed	14	1.0m	MISMATCH	1
❌ step-vs-step-fork	completed	12	0ms	MISMATCH	1
❌ step-vs-step-fork-fenced	completed	12	0ms	MISMATCH	1
✅ fence-catches-benign-direction	completed	12	5ms	ok	0
❌ in-flight-before-decision	completed	17	1.0m	MISMATCH	1
✅ in-flight-before-decision-counted	completed	20	1.0m	ok	0
❌ in-flight-after-decision	failed	14	2.0m	MISMATCH	1
✅ 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-mint.txt

🟢 Append-only log — 0 fail of 41 total

log=append-only · 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
✅ 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-append-only.txt