* feat: add clickable Run reference rendering in observability UI
When a serialized Run object appears in step input/output data, it is
now rendered as a clickable purple badge showing the runId. Clicking
navigates to the target run's detail page.
Changes:
- serialization-format.ts: Add RunRef type, isRunRef(), serializedRunToRunRef(),
and 'Run' entry in observabilityRevivers
- data-inspector.tsx: Add RunRefInline component (purple badge), RunClickContext,
collapseRefs() to make refs non-expandable in ObjectInspector
- attribute-panel.tsx: Thread onRunClick prop, wrap in RunClickContext.Provider
- entity-detail-panel.tsx: Thread onRunClick prop
- run-trace-view.tsx: Thread onRunClick prop
- workflow-trace-view.tsx: Thread onRunClick prop, reset selected span on run change
- trace-span-construction.ts: Show step name for builtin steps instead of empty string
- hydration.ts: Re-export RunRef types
- run-detail-view.tsx: Add handleRunRefClick that navigates to /run/{targetRunId}
* fix: guard collapseRefs against class instances and memoize result
Only recurse into plain objects (prototype is Object.prototype or null)
to avoid stripping class instances like Date, Error, Map, etc. that
have their own rendering in NodeRenderer. Also memoize the collapsed
result to avoid recomputing on every render.
* fix: detect Run instances in Instance reviver instead of fake Run serde key
The Run class goes through the standard Instance serialization pipeline
(WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE), not a dedicated 'Run' key.
Move the RunRef detection into serializedInstanceToRef() which checks
if the className is 'Run' and the data contains a runId string, then
returns a RunRef instead of a generic ClassInstanceRef.
* fix: use serializedInstanceToRef in web and CLI Instance revivers
Both the web and CLI hydration layers override the observabilityRevivers
Instance handler with their own implementation (for react-inspector
named constructors and CLI inspect.custom respectively), bypassing the
RunRef detection in serializedInstanceToRef. Fix by calling
serializedInstanceToRef first and returning a RunRef when detected.
* Make encrypted markers clickable to trigger decryption and detect encryption at run level before span selection
* Make encrypted markers clickable to trigger decryption and detect encryption at run level before span selection
* Make encrypted markers clickable to trigger decryption and detect encryption at run level before span selection
* Make encrypted markers clickable to trigger decryption and detect encryption at run level before span selection
* Make encrypted markers clickable to trigger decryption and detect encryption at run level before span selection
* move swc-playground-wasm into workbench/swc-playground
Move the Rust/WASM source from packages/swc-playground-wasm into
workbench/swc-playground/wasm/ so it is no longer built as part of
the packages/* turbo filter in CI. The WASM build now runs as part
of the playground's own prebuild/dev scripts, avoiding Rust toolchain
failures in unrelated CI jobs.
* fix: ensure default rustup toolchain in wasm build
The Vercel build environment has rustup installed but no default
toolchain configured. Add a check for this and install stable
if needed. Also check for VERCEL env var in addition to CI.
* fix: ensure cargo bin dir is in PATH on Vercel
After cargo install wasm-pack, the binary lives in $CARGO_HOME/bin
which may not be in PATH on the Vercel build environment. Always
add the cargo bin directory to PATH after ensuring the toolchain.
Move `workflow/runtime` resolution from `createStepsBundle` into
`discoverEntries` so callers pass the original `inputFiles` array
reference. This restores the WeakMap cache hit when
`createWorkflowsBundle` and `createStepsBundle` are called with
the same inputFiles, avoiding a redundant second esbuild discovery
pass per build that was causing E2E Local Dev Tests to flake on CI.
* fix(next): resolve next/package.json from working directory first
In npm workspaces monorepos, `@workflow/next` can be hoisted to the root
`node_modules/` while `next` stays in a workspace's local `node_modules/`.
The eager `require('next/package.json')` on the fallback path resolved
relative to `@workflow/next`'s own location, failing before the correct
working-directory-relative resolution could run.
Restructure `resolveNextVersion()` to try the working directory path first,
fall back to the package-relative path second, and wrap both in separate
try/catch blocks so neither can crash the process.
Closes#1680
* fix(next): capture resolution errors and include workingDir in error message
Address review feedback: capture caught errors from both resolution
attempts and attach them via `cause` on the final thrown error. Include
the working directory in the error message to aid debugging in monorepo
and CI environments.
* feat(core): add serialization support for workflow function references
Add a WorkflowFunction reducer/reviver pair so that workflow function
references (functions with a .workflowId property, as produced by the
SWC compiler) can cross the step serialization boundary.
Reducer: detects functions with a .workflowId string property, serializes
as { workflowId }. Only matches functions (not plain objects) to prevent
infinite recursion since the reduced form is a plain object.
Reviver: deserializes as a plain { workflowId } metadata object, which
start() already accepts via its WorkflowFunction | WorkflowMetadata
parameter type.
Also adds an observability reviver that renders as '<workflow:workflowId>'.
* fix: address review feedback - fix error assertion, add o11y reviver test
* fix(world-vercel): include runId in streams.get() request URL
streams.get() was ignoring the runId parameter and hardcoding undefined,
causing requests to hit /api/v2/stream/:streamId instead of the correct
/api/v2/runs/:runId/stream/:streamId. Also removes the fallback path in
getStreamUrl() that allowed omitting runId.
* test(world-vercel): add regression test for streams.get() runId in URL
The correlationId was generated as hc_${generateId()}, but
generateHealthCheckRunId() already adds wrun_hc_, producing
wrun_hc_hc_... Similarly, getHealthCheckStreamName() adds
__health_check__, making the hc_ prefix in correlationId redundant.
* feat: serialize Run via custom class serialization with "use step"
Single Run class implementation:
- Add WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE to core Run class
- Mark all runtime-dependent methods/getters with "use step" so SWC
strips their bodies from the workflow bundle
- Remove duplicate Run stub from api-workflow.ts; re-export core Run
- SWC auto-registers the class (no manual registerSerializationClass)
- Add e2e test for Run serialization across workflow/step boundaries
- Add unit tests for serde roundtrip
* chore: bump changeset to minor (new feature)
* fix: include resilientStart in Run serde payload and add readable getter comment
* .
* fix: remove eager getWorld() from constructor, rely on lazy getter
* fix(builders): improve step bundle discovery and externalization for SDK serde classes
- Broaden importParents tracking to all imports (not just file extensions)
so parentHasChild() works through bare specifier imports
- Include workflow/runtime in discovery inputs so SDK serde classes like
Run are always discovered
- Bundle node_modules deps instead of externalizing with broken relative
paths in CJS shims
* fix(builders): address review feedback
- Preserve inputFiles array reference for discoverEntries() WeakMap
caching when no extra entries are needed
- Add test verifying importParents/parentHasChild works through bare
specifier imports (entry -> bare-pkg -> serde file)
* feat(swc): dead code eliminate unreferenced private class members in workflow mode
After stripping 'use step' methods from a class body in workflow mode,
eliminate private members (both JS native #field/#method and TypeScript
private field/private method) that are no longer referenced by any
remaining public member.
The algorithm is iterative: references are seeded from public members,
then expanded through surviving private members until a fixed point,
enabling cascading elimination (e.g. a private field only referenced by
a private method that is itself unreferenced).
* test(swc): add fixture for JS native private member DCE (#field, #method)
* fix(swc): address review feedback on private member DCE
- Namespace JS native private names with # prefix to avoid collisions
with TS private members of the same name
- Track TS private member accesses on non-this receivers (e.g. a.x in
static methods) by maintaining a set of known TS-private names
- Use visit_children_with for full traversal including computed member
expressions
- Extract retain logic into shared retain_referenced_private_members()
helper used by both visit_mut_class_decl and visit_mut_class_expr
* fix(next): resolve bare specifiers in copied step files for lazy discovery
When the deferred builder copies step files to __workflow_step_files__/,
bare specifiers that are transitive SDK deps can't resolve from the app
directory. Use enhanced-resolve with ESM conditions (preferring 'import'
over 'require') to resolve from the original source location, only when
the specifier can't be resolved from the app directory.
Also add enhanced-resolve to the pnpm catalog and use catalog: in both
@workflow/builders and @workflow/next.
* fix(next): address review feedback on lazy discovery resolver
- Cache ESM/CJS resolvers as class fields instead of re-creating per call
- Remove redundant try/catch (resolveBareCopiedStepSpecifier already
returns undefined on failure)
- Use shared NODE_RESOLVE_OPTIONS / NODE_ESM_RESOLVE_OPTIONS matching
the configuration in swc-esbuild-plugin.ts for consistent resolution
* Followup fixes for sync step function support
Address review feedback from #1633 (merged):
- Remove dangling incomplete comment from validate_async_function removal
- Restore export validation for file-level 'use step' files: allow
sync/async function exports, reject non-function exports (constants,
classes, re-exports) which can pull Node-only code into bundles
- Fix InvalidExport error message: 'Only functions can be exported'
for step files vs 'Only async functions can be exported' for workflow
- Update spec.md error table and supported function forms to document
sync step support
- Add sync-step-class test fixture (sync static methods, sync function
expressions with var/let)
- Add sync-workflow error test (sync workflow still errors)
* Tighten step file export validation, fix spec completeness
- Reject uninitialized var exports (export let x) in step files
- Reject local named exports (export { value }) in step files since
we cannot statically verify the binding is a function
- Add test coverage for both new rejection cases
- Add sync variants for let/var arrow functions in spec.md
* Add test fixtures for remaining export validation edge cases
- Add re-export with specifiers to invalid-exports (export { x } from)
- Add error fixture for default class export in step files
- Add fixture for sync default function export (should pass)
- Total: 220 tests (165 fixture + 33 error + 22 unit)
* Remove isWorkflowSdkFile serde exclusion
The SWC detect mode's AST-level manifest (hasManifestEntries) already
correctly filters files without serde class definitions. The broad
isWorkflowSdkFile path exclusion is redundant and was preventing
class definitions in SDK packages from being discovered.
Removed from: builders, next, rollup
* Address review feedback: major semver bump, fix doc comment, add tests
- Bump changeset to major (removing exported APIs is breaking)
- Fix misleading doc comment referencing 'detect mode' in shouldTransformFile
- Add unit tests for shouldTransformFile covering all code paths
* Add AST-level serde filtering to Next.js deferred builder
The isWorkflowSdkFile path-based exclusion was removed from all paths,
but the Next.js deferred builder (collectTransitiveSerdeFiles) was still
using regexp-only detection, causing SDK internal files to be bundled
into the workflow sandbox and triggering stack overflows.
Fix: add applySwcTransform('detect', ...) verification at the end of
collectTransitiveSerdeFiles(). Regex-matched serde candidates are now
verified via the SWC plugin's AST-level manifest to confirm they
actually define serde classes before inclusion in the bundle.
* Add features.encryption to WorkflowMetadata
Expose a `features` object on `getWorkflowMetadata()` so library
authors can detect at runtime whether encryption is enabled for the
current workflow run, allowing them to conditionally handle sensitive
data serialization.
* Improve docs example: show workflow-level encryption check
Step inputs are serialized before the step body runs, so the encryption
check should happen in the workflow function before passing data to
steps.
* Fix docs example: show encryption check on step return value
Step return values are serialized to the event log after the step body
runs, so this is where the check is actually useful - controlling what
data gets persisted as output.
* Fix docs typecheck: declare external function in code sample
* minor
Lift the async function restriction from "use step" in both the SWC
compiler plugin and the TypeScript language service plugin. This enables
using "use step" as a mechanism to strip Node.js-dependent code from
the workflow VM bundle without requiring the function to be async.
The async restriction is preserved for "use workflow" functions.
- SWC plugin: removed async guards from all step function code paths,
updated should_transform_function, updated InvalidExport validation
- TypeScript plugin: removed error 9002 for sync step functions
- Added sync-step fixture test, cleaned up error test fixtures
- Updated spec.md error documentation
The SWC compiler plugin no longer generates import statements. All step
function registrations and closure variable access are now self-contained
inline IIFEs with zero module dependencies
Use named export instead of `export =` in the CJS shim so that
Node.js cjs-module-lexer can detect withWorkflow as a named export,
enabling `import { withWorkflow } from 'workflow/next'` in ESM.
* Add detect mode to SWC plugin for false positive directive filtering
Add a new 'detect' mode to the SWC workflow plugin that walks the AST
to find directives and serde patterns and emits the manifest, but does
not transform any code. The discover-entries plugin now uses a two-phase
approach: fast regexp pre-scan to filter out most files, then SWC detect
mode on candidates to validate at the AST level. This eliminates false
positives where directive-like strings appear inside template literals
or other non-code contexts. The mode:false syntax-only transform is also
removed since esbuild handles TypeScript natively.
* Keep SWC syntax transform in discover phase for decorator support
esbuild does not support legacy decorators or emitDecoratorMetadata,
so all files still need the SWC syntax transform (TS→JS) during
discovery. For regexp-matched files the 'detect' mode handles both
the syntax transform and manifest in a single pass; for all other
files the existing mode:false call is used.
* Use Set for discoveredWorkflows/Steps/SerdeFiles
Eliminates the manual .includes() dedup check and prevents duplicate
entries structurally.
* Update DeferredDiscoveredEntries to use Set<string>
* Add @workflow/next to changeset
* Support getter functions with "use step" directive
Add SWC compiler plugin support for JavaScript getters marked with
"use step", enabling patterns like `await obj.prop` where the getter
triggers a step function invocation.
- Handle Prop::Getter in object literals and MethodKind::Getter in classes
- Emit Object.getOwnPropertyDescriptor registration in step mode
- Emit hoisted proxy + Object.defineProperty in workflow mode
- Emit error for getters with "use workflow"
- Fix @vercel/workflow -> @workflow/serde imports in existing fixtures
- Update spec.md with getter transformation documentation
* Add changeset for getter step support
* Add e2e test for getter step functions
* Add static getter support, sanitize hoisted var identifiers
Address PR review feedback:
- Support static getters with "use step" using ClassName (not .prototype)
- Add sanitize_ident_part() to produce valid JS identifiers from getter
names that may contain special characters (e.g. string literal keys)
- Add static-getter-step test fixture
- Update spec.md with static getter transformation documentation
* Remove duplicate getter workflow error in visit_mut_prop_or_spread
The previous pre-release versions (4.x.y-beta.N) caused two issues:
- semver.inc('4.0.0-beta.N', 'major') returns 4.0.0, not 5.0.0
- Pre-release numbers carried over (beta.61 -> beta.62 instead of beta.0)
Setting all versions to 4.0.0 (non-pre-release) ensures a clean major
bump to 5.0.0-beta.0. Also removes @workflow/swc-playground-wasm from
the changeset and pre.json since it is a private package.
* docs: clarify Next monorepo setup
Prevent confusion when Next.js apps live below the repository root and workflow code imports sibling workspace packages.
This documents the output tracing root requirement at the point where users configure withWorkflow, so monorepo setups follow the same working patterns as the shipped Next.js integration instead of failing due to unresolved workspace imports.
Ploop-Iter: 1
* ploop: iteration 2 checkpoint
Automated checkpoint commit.
Ploop-Iter: 2
* ploop: iteration 3 checkpoint
Automated checkpoint commit.
Ploop-Iter: 3
* docs: audit recent documentation coverage
Capture recent workflow documentation updates so the public docs and package guidance stay aligned with the implementation and current docs-typecheck behavior.
Ploop-Iter: 1
* docs: align docs-typecheck docs
Document the current docs verification contract so contributors do not assume JavaScript examples are type-checked when only TypeScript snippets are enforced today.
Add regression coverage around the README language and framework integration guidance to keep those docs aligned with the implemented Next.js and docs-typecheck behavior as future changes land.
Ploop-Iter: 2
* docs: add start() troubleshooting guidance
Document the most common causes of the invalid workflow function error so users can resolve start() failures from the API docs and Next.js setup flow without having to infer build-time requirements from runtime behavior.
Keep the new troubleshooting page aligned with the shipped runtime message and add regression coverage so future wording or cross-link changes do not silently break that guidance.
Ploop-Iter: 3
* docs: align NestJS setup docs
Document both supported NestJS module formats and add a regression check so the getting-started guide stays aligned with the package README as the integration evolves.
Ploop-Iter: 1
* docs: tighten NestJS CommonJS guidance
Keep the NestJS getting-started guide consistent across the ESM and CommonJS paths so readers do not mix module settings or import styles mid-setup.
Strengthen the docs regression coverage around the later guide sections so future edits are more likely to preserve the supported CommonJS path documented in the package README.
Ploop-Iter: 2
* docs: align docs with recent workflow guidance
Document the recently added troubleshooting and observability patterns so the public docs stay aligned with the behavior users now encounter in practice.
This keeps the NestJS guide, workflow API reference, and docs regression coverage in sync with the runtime-facing guidance from recent changes.
Ploop-Iter: 3
* docs: audit docs coverage
Why: keep the docs aligned with recent API and runtime behavior changes so examples and reference pages don’t drift from the supported surface.
Ploop-Iter: 1
* test: add docs audit guards
Add regression coverage for doc surfaces that are easy to drift from implementation so docs audits catch mismatches early and keep published guidance aligned with the supported API surface.
Ploop-Iter: 2
* docs: add docs audit guards
Keep new observability and server-testing guidance anchored to machine-readable interfaces so follow-up implementation changes do not silently drift away from the documented agent and automation patterns.
Ploop-Iter: 3
* docs: align observability troubleshooting guidance
Keep the docs consistent so users get the same guidance when debugging hook token collisions and correlating workflow events with platform logs.
This prevents the event-sourcing reference from drifting away from the observability and error docs, and adds guard tests to catch regressions.
Ploop-Iter: 1
* Remove the unreferenced image file img-a-clean-minimal-technical-architecture-d-2026-02-27T14-07-52-1.png from the repo root, workbench/fastify/public/index.html (a Nitro example mistakenly placed in the fastify workbench by a ploop checkpoint), all .claude/worktrees/* submodule references, and all 15 string-presence audit guard tests in packages/docs-typecheck/src/__tests__/ (they only assert keyword presence, not semantic correctness). None of these belong in the docs audit PR.
* Address all PR #1466 review feedback from VaguelySerious, pranaygp, and ijjk:
1. Remove the "Machine-Readable Surfaces" section from docs/content/docs/observability/index.mdx (reviewers say it's unnecessary and already in world docs)
2. Remove all @skip-typecheck annotations from durable-agent.mdx (8) and server-based.mdx (1) — types exist in built packages/ai/dist after pnpm build
3. In durable-agent.mdx, change "machine-readable tool activity" to "tool call details" in the stream() return description
4. In durable-agent.mdx "Aborting Long-Running Streams" section, add a warning callout that abortSignal is not yet supported (blocked by #1301), recommend timeout instead
5. In event-sourcing.mdx, update requestId description: "On Vercel, requestId is the platform request ID when available. Other worlds are not expected to provide a requestId."
6. In get-world.mdx, change "user-friendly names from the machine-readable workflowName field" to "human-readable names from the workflowName field"
7. In start-invalid-workflow-function.mdx, add "// Does NOT work" comment above the bad example line
8. In with-workflow.mdx: reframe outputFileTracingRoot as a workaround (Next.js auto-detects by default per ijjk); change options description from "control local development behavior" to "configure the Next.js integration"; scope the callout to "workflows.local options only affect local development"
9. Drop the withWorkflow() options callout from docs/content/docs/getting-started/next.mdx
10. Remove the Next.js-specific outputFileTracingRoot callout from framework-integrations.mdx
11. Add a Troubleshooting section with the start() invalid-workflow-function error to all 9 non-Next getting-started guides (astro, express, fastify, hono, nestjs, nitro, nuxt, sveltekit, vite), each with framework-appropriate config check in point 2
* docs: absorb unique accuracy fixes from PR #1200
Cherry-picked 6 still-needed fixes from #1200 that aren't covered by
this audit PR or #1516:
- Fix npx workflow description (observability)
- Remove fetch from restricted modules list (errors)
- Fix package name @workflow-worlds/postgres → @workflow/world-postgres (deploying)
- Fix stream wording (foundations/starting-workflows)
- Fix import path simple → simple-streaming (foundations/streaming)
- Add close(), getEncryptionKeyForRun(), writeToStreamMulti() to World interface,
update create() and streamer signatures (deploying/building-a-world)
* docs: address review feedback on March docs audit
- durable-agent.mdx: "structured tool activity" → "tool call information"
per VaguelySerious's suggestion
- next.mdx: drop monorepo callout from getting-started per pranaygp
(too much context too early; info is in withWorkflow API ref)
* docs: fix 2 typecheck failures in encryption and nestjs guides
- encryption.mdx: add skip-typecheck for interface signature block
(getEncryptionKeyForRun overloads are not runnable code)
- nestjs.mdx: add skip-typecheck for WorkflowModule.forRoot config
snippet (fragment inside callout, full import shown above)
Verified: pnpm vitest run passes 300/300 in docs-typecheck.
The `dataDir` option was accepted in the type definition but never
read — `WORKFLOW_LOCAL_DATA_DIR` was unconditionally set to
`.next/workflow-data`. Remove the dead option to avoid confusion.
Karthik Kalyan