Summary
how-it-works/code-transform.mdx §"ID Generation" (v4:309-329, v5:311-329) documents only the local-file ID form {type}//{filepath}//{functionName} and never mentions the package-shipped form {type}//{name}/{subpath}@{version}//{functionName} (produced by packages/builders/src/module-specifier.ts:370-402 for export-reachable package files).
Not wrong, but incomplete in exactly the direction that made the #3152 error plausible: a reader learns IDs come from file paths, so "re-export into my workflows/ dir → my path → my ID" is a natural inference — the same inference #3153 corrects in publishing-libraries.mdx.
Suggested fix
Add the package-shipped form to the ID Generation section, next to the local-file form, with one line on when each applies (workspace/local files vs. export-reachable npm package files). The section's existing callout already states deployment pinning correctly ("changing IDs won't break old workflows from running, but will prevent runs from being upgraded"), so only the ID-form table/list needs the addition.
Related: #3152, #3153. Found during a docs sweep while building the Mastra integration.
Summary
how-it-works/code-transform.mdx§"ID Generation" (v4:309-329, v5:311-329) documents only the local-file ID form{type}//{filepath}//{functionName}and never mentions the package-shipped form{type}//{name}/{subpath}@{version}//{functionName}(produced bypackages/builders/src/module-specifier.ts:370-402for export-reachable package files).Not wrong, but incomplete in exactly the direction that made the #3152 error plausible: a reader learns IDs come from file paths, so "re-export into my
workflows/dir → my path → my ID" is a natural inference — the same inference #3153 corrects inpublishing-libraries.mdx.Suggested fix
Add the package-shipped form to the ID Generation section, next to the local-file form, with one line on when each applies (workspace/local files vs. export-reachable npm package files). The section's existing callout already states deployment pinning correctly ("changing IDs won't break old workflows from running, but will prevent runs from being upgraded"), so only the ID-form table/list needs the addition.
Related: #3152, #3153. Found during a docs sweep while building the Mastra integration.