docs: correct the workflow ID claim in publishing libraries - #3153
Conversation
The consumer re-export file does not relocate a library's workflow and step IDs into the consumer's source tree. An ID is derived from where the file lives, so any export-reachable package file keeps a name@version ID whether or not it is re-exported. Rename the section to describe what the re-export actually does — put the package's directive files on the compiler's discovery graph and give the entry point a resolvable address — and add the upgrade guidance that follows from the real behavior: a package version bump renames every workflow and step it ships, so in-flight runs must drain first. The wrong claim also appeared in the page summary and the CopyPrompt, so it is corrected in all three places, in both the v4 and v5 copies. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: Pranay Prakash <pranay.gp@gmail.com>
|
Runs are pinned to the deployment that recorded their step IDs, so a library version bump does not strand in-flight runs: new runs execute the new version, in-flight runs keep replaying on their original deployment. Replaces the incorrect drain-before-upgrade advice. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: Pranay Prakash <pranay.gp@gmail.com>
There was a problem hiding this comment.
Pull request overview
Corrects the “Publishing Libraries” docs to accurately explain why consumers must re-export a library’s workflow entry point: to ensure the compiler discovers and transforms the library’s "use workflow" / "use step" files, not to “relocate” IDs for stability across package upgrades. This aligns the guidance with the builder’s actual module-specifier behavior (package-shipped IDs include name@version).
Changes:
- Renames and rewrites the re-export section to focus on compiler discovery/import-graph inclusion rather than ID stability.
- Adds explicit upgrade guidance warning that package version bumps change IDs and can break in-flight runs; re-exporting does not prevent this.
- Updates frontmatter summary,
<CopyPrompt>text, and the in-page anchor reference; adds a checklist item to drain in-flight runs before upgrading.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| docs/content/docs/v5/cookbook/advanced/publishing-libraries.mdx | Rewrites re-export guidance to reflect compiler discovery and adds upgrade warning/checklist item. |
| docs/content/docs/v4/cookbook/advanced/publishing-libraries.mdx | Mirrors the same corrections in the v4 docs copy for consistency. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: Pranay Prakash <pranay.gp@gmail.com>
VaguelySerious
left a comment
VaguelySerious
left a comment
There was a problem hiding this comment.
LGTM but see one comment
| The workflow compiler only transforms files it discovers, and discovery starts from the consumer's `workflows/` directory and follows imports out from there. A library's workflow functions are not on that graph by default, so nothing compiles them and the runtime has no definition to run. | ||
|
|
||
| The fix is a **re-export file**. The consumer creates a file in their `workflows/` directory that re-exports the library's workflows. The build system then processes this file and assigns stable IDs. | ||
| The fix is a **re-export file**. The consumer creates a file in their `workflows/` directory that re-exports the library's workflows, which pulls the library's source onto the discovery graph and gives its entry point an address the runtime can resolve. |
There was a problem hiding this comment.
Don't we also look at the framework entrypoint and follow that?
|
No backport to The commit only edits To override, re-run the Backport to stable workflow manually via |
Fixes #3152
The problem
The "Re-Exporting for Workflow ID Stability" section tells library authors that the consumer re-export file relocates a library's workflow and step IDs into the consumer's source tree, where they then survive package upgrades. That is not what happens.
resolveModuleSpecifier(packages/builders/src/module-specifier.ts:370-402) derives an ID from where a file lives, not from how it was imported. Any file undernode_modulesor a workspace package that is reachable through the package'sexportsmap gets${pkg.name}${subpath}@${pkg.version}— re-exported or not. So a package version bump renames every workflow and step the package ships, and the re-export file does nothing to prevent it.That renaming is intended invalidation rather than a hazard, because runs are pinned to the deployment that recorded their IDs: resume re-enqueues against
workflowRun.deploymentId(packages/core/src/runtime/resume-hook.ts:215-227,runs.ts:168), and moving a run onto newer code takes an explicitdeploymentId: 'latest'(start.ts:279-306). After a consumer upgrades, new runs execute the new version and in-flight runs keep replaying on the deployment that started them.The fix
Surgical correction to the one section, in both the v4 and v5 copies (they were byte-identical before and after).
workflows/directory and follows imports, so the re-export is what puts the package's"use workflow"/"use step"files on that graph and gives the entry point a resolvable address. The re-export is still required — only the reason changes.step//@acme/media/workflows@1.4.0//transcode), deployment pinning is what makes a version bump safe, and re-exporting does not change either fact../workflowsexport over a deepdist/path, since only export-reachable files get thename/subpath@versionform; deeper files fall back to a path-based ID.The claim had also spread beyond the prose, so it is corrected in all three places it appeared: the section body, the page
summaryfrontmatter, and the<CopyPrompt>text. The CopyPrompt one matters most — it was instructing agents to document the wrong rationale into every library scaffolded from this page. The in-page anchor link at line 257 is updated to the renamed heading; no other page links to the old anchor.The second commit walks back a wrong turn in the first: it had replaced one incorrect claim ("IDs are stable across upgrades") with another ("in-flight runs cannot replay across an upgrade — drain them first"), missing the deployment pinning above. The page now describes the pinning instead, and the drain checklist item is gone.
Alternative resolution
If the team would rather fix the compiler than the docs — strip versions from package-shipped IDs, or relocate them on re-export so the current promise becomes true — that is a perfectly good way to close #3152, and this PR should be dropped in favor of it. This only makes the docs honest about today's behavior.
Related
Found while writing the Mastra integration cookbook page (#3150), which originally repeated this claim and no longer does.
Pinning is per-world, so the callout is scoped to "worlds with deployment pinning, such as Vercel" rather than stating it flatly:
world-vercelpreservesdeploymentIdacross re-enqueue (packages/world-vercel/src/queue.ts:406,417-418,490),world-localpins only per SDK version (packages/world-local/src/queue.ts:400-402), andworld-postgresreturns a constant (packages/world-postgres/src/queue.ts:133-135), so replay there breaks on any code change, not just a library upgrade. The page does not spell out that postgres case: it is a general self-hosting property rather than something a library author controls — happy to add a line if reviewers disagree.Testing
Docs CI: Docs Code Samples, Docs Links, Docs Preview Smoke Checks.
🤖 Generated with Claude Code