workflow 5.0.0-beta.53 → 5.0.0-beta.55

package/dist/api-workflow.d.ts

@@ -6,4 +6,6 @@ export declare const getHookByToken: () => never;
 export declare const resumeHook: () => never;
 export declare const resumeWebhook: () => never;
 export declare const runStep: () => never;
+export declare const registerLifecycleHooks: () => never;
+export type { RunCompletedHookParams, RunFailedHookParams, WorkflowLifecycleHooks, } from '@workflow/core/runtime/lifecycle-hooks';
 //# sourceMappingURL=api-workflow.d.ts.map

package/dist/api-workflow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-workflow.d.ts","sourceRoot":"","sources":["../src/api-workflow.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,gBAAgB,EAChB,KAAK,EACL,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,6BAA6B,EAC7B,WAAW,EACX,gCAAgC,GACjC,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,GAAG,EAAE,MAAM,4BAA4B,CAAC;AACjD,OAAO,EAAE,KAAK,EAAE,MAAM,8BAA8B,CAAC;AAQrD,eAAO,MAAM,MAAM,aAA+B,CAAC;AACnD,eAAO,MAAM,cAAc,aAAuC,CAAC;AACnE,eAAO,MAAM,UAAU,aAAmC,CAAC;AAC3D,eAAO,MAAM,aAAa,aAAsC,CAAC;AACjE,eAAO,MAAM,OAAO,aAAgC,CAAC"}
+{"version":3,"file":"api-workflow.d.ts","sourceRoot":"","sources":["../src/api-workflow.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,gBAAgB,EAChB,KAAK,EACL,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,6BAA6B,EAC7B,WAAW,EACX,gCAAgC,GACjC,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,GAAG,EAAE,MAAM,4BAA4B,CAAC;AACjD,OAAO,EAAE,KAAK,EAAE,MAAM,8BAA8B,CAAC;AAQrD,eAAO,MAAM,MAAM,aAA+B,CAAC;AACnD,eAAO,MAAM,cAAc,aAAuC,CAAC;AACnE,eAAO,MAAM,UAAU,aAAmC,CAAC;AAC3D,eAAO,MAAM,aAAa,aAAsC,CAAC;AACjE,eAAO,MAAM,OAAO,aAAgC,CAAC;AACrD,eAAO,MAAM,sBAAsB,aACK,CAAC;AACzC,YAAY,EACV,sBAAsB,EACtB,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,wCAAwC,CAAC"}

package/dist/api-workflow.js

@@ -8,4 +8,5 @@ export const getHookByToken = () => workflowStub('getHookByToken');
 export const resumeHook = () => workflowStub('resumeHook');
 export const resumeWebhook = () => workflowStub('resumeWebhook');
 export const runStep = () => workflowStub('runStep');
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYXBpLXdvcmtmbG93LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2FwaS13b3JrZmxvdy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFXQSxPQUFPLEVBQUUsR0FBRyxFQUFFLE1BQU0sNEJBQTRCLENBQUM7QUFDakQsT0FBTyxFQUFFLEtBQUssRUFBRSxNQUFNLDhCQUE4QixDQUFDO0FBRXJELE1BQU0sWUFBWSxHQUFHLENBQUMsSUFBWSxFQUFFLEVBQUU7SUFDcEMsTUFBTSxJQUFJLEtBQUssQ0FDYixnRUFBZ0UsSUFBSSwyRkFBMkYsQ0FDaEssQ0FBQztBQUNKLENBQUMsQ0FBQztBQUVGLE1BQU0sQ0FBQyxNQUFNLE1BQU0sR0FBRyxHQUFHLEVBQUUsQ0FBQyxZQUFZLENBQUMsUUFBUSxDQUFDLENBQUM7QUFDbkQsTUFBTSxDQUFDLE1BQU0sY0FBYyxHQUFHLEdBQUcsRUFBRSxDQUFDLFlBQVksQ0FBQyxnQkFBZ0IsQ0FBQyxDQUFDO0FBQ25FLE1BQU0sQ0FBQyxNQUFNLFVBQVUsR0FBRyxHQUFHLEVBQUUsQ0FBQyxZQUFZLENBQUMsWUFBWSxDQUFDLENBQUM7QUFDM0QsTUFBTSxDQUFDLE1BQU0sYUFBYSxHQUFHLEdBQUcsRUFBRSxDQUFDLFlBQVksQ0FBQyxlQUFlLENBQUMsQ0FBQztBQUNqRSxNQUFNLENBQUMsTUFBTSxPQUFPLEdBQUcsR0FBRyxFQUFFLENBQUMsWUFBWSxDQUFDLFNBQVMsQ0FBQyxDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiZXhwb3J0IHR5cGUge1xuICBDYW5jZWxSdW5PcHRpb25zLFxuICBFdmVudCxcbiAgU3RhcnRPcHRpb25zLFxuICBTdG9wU2xlZXBPcHRpb25zLFxuICBTdG9wU2xlZXBSZXN1bHQsXG4gIFdvcmtmbG93UmVhZGFibGVTdHJlYW1PcHRpb25zLFxuICBXb3JrZmxvd1J1bixcbiAgV29ya2Zsb3dSdW5Xcml0YWJsZVN0cmVhbU9wdGlvbnMsXG59IGZyb20gJ0B3b3JrZmxvdy9jb3JlL3J1bnRpbWUnO1xuXG5leHBvcnQgeyBSdW4gfSBmcm9tICdAd29ya2Zsb3cvY29yZS9ydW50aW1lL3J1bic7XG5leHBvcnQgeyBzdGFydCB9IGZyb20gJ0B3b3JrZmxvdy9jb3JlL3J1bnRpbWUvc3RhcnQnO1xuXG5jb25zdCB3b3JrZmxvd1N0dWIgPSAoaXRlbTogc3RyaW5nKSA9PiB7XG4gIHRocm93IG5ldyBFcnJvcihcbiAgICBgVGhlIHdvcmtmbG93IGVudmlyb25tZW50IGRvZXNuJ3QgYWxsb3cgdGhpcyBydW50aW1lIHVzYWdlIG9mICR7aXRlbX0uIE1vdmUgdGhpcyBjYWxsIHRvIGEgc3RlcCBmdW5jdGlvbiAoXCJ1c2Ugc3RlcFwiKSBvciBjYWxsIGl0IG91dHNpZGUgdGhlIHdvcmtmbG93IGNvbnRleHQuYFxuICApO1xufTtcblxuZXhwb3J0IGNvbnN0IGdldFJ1biA9ICgpID0+IHdvcmtmbG93U3R1YignZ2V0UnVuJyk7XG5leHBvcnQgY29uc3QgZ2V0SG9va0J5VG9rZW4gPSAoKSA9PiB3b3JrZmxvd1N0dWIoJ2dldEhvb2tCeVRva2VuJyk7XG5leHBvcnQgY29uc3QgcmVzdW1lSG9vayA9ICgpID0+IHdvcmtmbG93U3R1YigncmVzdW1lSG9vaycpO1xuZXhwb3J0IGNvbnN0IHJlc3VtZVdlYmhvb2sgPSAoKSA9PiB3b3JrZmxvd1N0dWIoJ3Jlc3VtZVdlYmhvb2snKTtcbmV4cG9ydCBjb25zdCBydW5TdGVwID0gKCkgPT4gd29ya2Zsb3dTdHViKCdydW5TdGVwJyk7XG4iXX0=
+export const registerLifecycleHooks = () => workflowStub('registerLifecycleHooks');
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYXBpLXdvcmtmbG93LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2FwaS13b3JrZmxvdy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFXQSxPQUFPLEVBQUUsR0FBRyxFQUFFLE1BQU0sNEJBQTRCLENBQUM7QUFDakQsT0FBTyxFQUFFLEtBQUssRUFBRSxNQUFNLDhCQUE4QixDQUFDO0FBRXJELE1BQU0sWUFBWSxHQUFHLENBQUMsSUFBWSxFQUFFLEVBQUU7SUFDcEMsTUFBTSxJQUFJLEtBQUssQ0FDYixnRUFBZ0UsSUFBSSwyRkFBMkYsQ0FDaEssQ0FBQztBQUNKLENBQUMsQ0FBQztBQUVGLE1BQU0sQ0FBQyxNQUFNLE1BQU0sR0FBRyxHQUFHLEVBQUUsQ0FBQyxZQUFZLENBQUMsUUFBUSxDQUFDLENBQUM7QUFDbkQsTUFBTSxDQUFDLE1BQU0sY0FBYyxHQUFHLEdBQUcsRUFBRSxDQUFDLFlBQVksQ0FBQyxnQkFBZ0IsQ0FBQyxDQUFDO0FBQ25FLE1BQU0sQ0FBQyxNQUFNLFVBQVUsR0FBRyxHQUFHLEVBQUUsQ0FBQyxZQUFZLENBQUMsWUFBWSxDQUFDLENBQUM7QUFDM0QsTUFBTSxDQUFDLE1BQU0sYUFBYSxHQUFHLEdBQUcsRUFBRSxDQUFDLFlBQVksQ0FBQyxlQUFlLENBQUMsQ0FBQztBQUNqRSxNQUFNLENBQUMsTUFBTSxPQUFPLEdBQUcsR0FBRyxFQUFFLENBQUMsWUFBWSxDQUFDLFNBQVMsQ0FBQyxDQUFDO0FBQ3JELE1BQU0sQ0FBQyxNQUFNLHNCQUFzQixHQUFHLEdBQUcsRUFBRSxDQUN6QyxZQUFZLENBQUMsd0JBQXdCLENBQUMsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbImV4cG9ydCB0eXBlIHtcbiAgQ2FuY2VsUnVuT3B0aW9ucyxcbiAgRXZlbnQsXG4gIFN0YXJ0T3B0aW9ucyxcbiAgU3RvcFNsZWVwT3B0aW9ucyxcbiAgU3RvcFNsZWVwUmVzdWx0LFxuICBXb3JrZmxvd1JlYWRhYmxlU3RyZWFtT3B0aW9ucyxcbiAgV29ya2Zsb3dSdW4sXG4gIFdvcmtmbG93UnVuV3JpdGFibGVTdHJlYW1PcHRpb25zLFxufSBmcm9tICdAd29ya2Zsb3cvY29yZS9ydW50aW1lJztcblxuZXhwb3J0IHsgUnVuIH0gZnJvbSAnQHdvcmtmbG93L2NvcmUvcnVudGltZS9ydW4nO1xuZXhwb3J0IHsgc3RhcnQgfSBmcm9tICdAd29ya2Zsb3cvY29yZS9ydW50aW1lL3N0YXJ0JztcblxuY29uc3Qgd29ya2Zsb3dTdHViID0gKGl0ZW06IHN0cmluZykgPT4ge1xuICB0aHJvdyBuZXcgRXJyb3IoXG4gICAgYFRoZSB3b3JrZmxvdyBlbnZpcm9ubWVudCBkb2Vzbid0IGFsbG93IHRoaXMgcnVudGltZSB1c2FnZSBvZiAke2l0ZW19LiBNb3ZlIHRoaXMgY2FsbCB0byBhIHN0ZXAgZnVuY3Rpb24gKFwidXNlIHN0ZXBcIikgb3IgY2FsbCBpdCBvdXRzaWRlIHRoZSB3b3JrZmxvdyBjb250ZXh0LmBcbiAgKTtcbn07XG5cbmV4cG9ydCBjb25zdCBnZXRSdW4gPSAoKSA9PiB3b3JrZmxvd1N0dWIoJ2dldFJ1bicpO1xuZXhwb3J0IGNvbnN0IGdldEhvb2tCeVRva2VuID0gKCkgPT4gd29ya2Zsb3dTdHViKCdnZXRIb29rQnlUb2tlbicpO1xuZXhwb3J0IGNvbnN0IHJlc3VtZUhvb2sgPSAoKSA9PiB3b3JrZmxvd1N0dWIoJ3Jlc3VtZUhvb2snKTtcbmV4cG9ydCBjb25zdCByZXN1bWVXZWJob29rID0gKCkgPT4gd29ya2Zsb3dTdHViKCdyZXN1bWVXZWJob29rJyk7XG5leHBvcnQgY29uc3QgcnVuU3RlcCA9ICgpID0+IHdvcmtmbG93U3R1YigncnVuU3RlcCcpO1xuZXhwb3J0IGNvbnN0IHJlZ2lzdGVyTGlmZWN5Y2xlSG9va3MgPSAoKSA9PlxuICB3b3JrZmxvd1N0dWIoJ3JlZ2lzdGVyTGlmZWN5Y2xlSG9va3MnKTtcbmV4cG9ydCB0eXBlIHtcbiAgUnVuQ29tcGxldGVkSG9va1BhcmFtcyxcbiAgUnVuRmFpbGVkSG9va1BhcmFtcyxcbiAgV29ya2Zsb3dMaWZlY3ljbGVIb29rcyxcbn0gZnJvbSAnQHdvcmtmbG93L2NvcmUvcnVudGltZS9saWZlY3ljbGUtaG9va3MnO1xuIl19

package/dist/api.d.ts

@@ -1,5 +1,6 @@
 import '@workflow/core/runtime/world-init';
 export type { CancelRunOptions, Event, StopSleepOptions, StopSleepResult, WorkflowRun, } from '@workflow/core/runtime';
+export { type RunCompletedHookParams, type RunFailedHookParams, registerLifecycleHooks, type WorkflowLifecycleHooks, } from '@workflow/core/runtime/lifecycle-hooks';
 export { getHookByToken, type Hook, type ResumedHook, resumeHook, resumeWebhook, } from '@workflow/core/runtime/resume-hook';
 export { getRun, Run, type WorkflowReadableStream, type WorkflowReadableStreamOptions, type WorkflowRunWritableStreamOptions, } from '@workflow/core/runtime/run';
 export { type StartOptions, start, } from '@workflow/core/runtime/start';

package/dist/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAOA,OAAO,mCAAmC,CAAC;AAE3C,YAAY,EACV,gBAAgB,EAChB,KAAK,EACL,gBAAgB,EAChB,eAAe,EACf,WAAW,GACZ,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,cAAc,EACd,KAAK,IAAI,EACT,KAAK,WAAW,EAChB,UAAU,EACV,aAAa,GACd,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACL,MAAM,EACN,GAAG,EACH,KAAK,sBAAsB,EAC3B,KAAK,6BAA6B,EAClC,KAAK,gCAAgC,GACtC,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,GACN,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAOA,OAAO,mCAAmC,CAAC;AAE3C,YAAY,EACV,gBAAgB,EAChB,KAAK,EACL,gBAAgB,EAChB,eAAe,EACf,WAAW,GACZ,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,sBAAsB,EACtB,KAAK,sBAAsB,GAC5B,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,cAAc,EACd,KAAK,IAAI,EACT,KAAK,WAAW,EAChB,UAAU,EACV,aAAa,GACd,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACL,MAAM,EACN,GAAG,EACH,KAAK,sBAAsB,EAC3B,KAAK,6BAA6B,EAClC,KAAK,gCAAgC,GACtC,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,GACN,MAAM,8BAA8B,CAAC"}

package/dist/api.js

@@ -6,7 +6,8 @@
 // stays host-only.
 // See `@workflow/core/src/runtime/world-init.ts` for the full rationale.
 import '@workflow/core/runtime/world-init';
+export { registerLifecycleHooks, } from '@workflow/core/runtime/lifecycle-hooks';
 export { getHookByToken, resumeHook, resumeWebhook, } from '@workflow/core/runtime/resume-hook';
 export { getRun, Run, } from '@workflow/core/runtime/run';
 export { start, } from '@workflow/core/runtime/start';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYXBpLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2FwaS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxxRUFBcUU7QUFDckUseUVBQXlFO0FBQ3pFLDJFQUEyRTtBQUMzRSw0RUFBNEU7QUFDNUUsNkVBQTZFO0FBQzdFLG1CQUFtQjtBQUNuQix5RUFBeUU7QUFDekUsT0FBTyxtQ0FBbUMsQ0FBQztBQVMzQyxPQUFPLEVBQ0wsY0FBYyxFQUdkLFVBQVUsRUFDVixhQUFhLEdBQ2QsTUFBTSxvQ0FBb0MsQ0FBQztBQUM1QyxPQUFPLEVBQ0wsTUFBTSxFQUNOLEdBQUcsR0FJSixNQUFNLDRCQUE0QixDQUFDO0FBQ3BDLE9BQU8sRUFFTCxLQUFLLEdBQ04sTUFBTSw4QkFBOEIsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8vIFNpZGUtZWZmZWN0IGltcG9ydDogZW5zdXJlIGB3b3JsZC50c2AgaXMgbG9hZGVkIHNvIGl0cyBtb2R1bGUtbG9hZFxuLy8gYGdsb2JhbFRoaXNbR2V0V29ybGRGbktleV0gPz89IGdldFdvcmxkYCByZWdpc3RyYXRpb24gZmlyZXMgYmVmb3JlIGFueVxuLy8gaG9zdCByb3V0ZSByZWFjaGVzIGBnZXRXb3JsZExhenkoKWAuIFdpdGhvdXQgdGhpcywgd2VicGFjay90dXJib3BhY2sgY2FuXG4vLyB0cmVlLXNoYWtlIGB3b3JsZC50c2Agb3V0IG9mIHJvdXRlcyB0aGF0IG9ubHkgdXNlIGBzdGFydGAuIFJlc29sdmVkIHRvIGFuXG4vLyBlbXB0eSBzdHViIHZpYSB0aGUgYHdvcmtmbG93YCBleHBvcnQgY29uZGl0aW9uIGluIFZNL3N0ZXAgYnVuZGxlcywgc28gdGhpc1xuLy8gc3RheXMgaG9zdC1vbmx5LlxuLy8gU2VlIGBAd29ya2Zsb3cvY29yZS9zcmMvcnVudGltZS93b3JsZC1pbml0LnRzYCBmb3IgdGhlIGZ1bGwgcmF0aW9uYWxlLlxuaW1wb3J0ICdAd29ya2Zsb3cvY29yZS9ydW50aW1lL3dvcmxkLWluaXQnO1xuXG5leHBvcnQgdHlwZSB7XG4gIENhbmNlbFJ1bk9wdGlvbnMsXG4gIEV2ZW50LFxuICBTdG9wU2xlZXBPcHRpb25zLFxuICBTdG9wU2xlZXBSZXN1bHQsXG4gIFdvcmtmbG93UnVuLFxufSBmcm9tICdAd29ya2Zsb3cvY29yZS9ydW50aW1lJztcbmV4cG9ydCB7XG4gIGdldEhvb2tCeVRva2VuLFxuICB0eXBlIEhvb2ssXG4gIHR5cGUgUmVzdW1lZEhvb2ssXG4gIHJlc3VtZUhvb2ssXG4gIHJlc3VtZVdlYmhvb2ssXG59IGZyb20gJ0B3b3JrZmxvdy9jb3JlL3J1bnRpbWUvcmVzdW1lLWhvb2snO1xuZXhwb3J0IHtcbiAgZ2V0UnVuLFxuICBSdW4sXG4gIHR5cGUgV29ya2Zsb3dSZWFkYWJsZVN0cmVhbSxcbiAgdHlwZSBXb3JrZmxvd1JlYWRhYmxlU3RyZWFtT3B0aW9ucyxcbiAgdHlwZSBXb3JrZmxvd1J1bldyaXRhYmxlU3RyZWFtT3B0aW9ucyxcbn0gZnJvbSAnQHdvcmtmbG93L2NvcmUvcnVudGltZS9ydW4nO1xuZXhwb3J0IHtcbiAgdHlwZSBTdGFydE9wdGlvbnMsXG4gIHN0YXJ0LFxufSBmcm9tICdAd29ya2Zsb3cvY29yZS9ydW50aW1lL3N0YXJ0JztcbiJdfQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYXBpLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2FwaS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxxRUFBcUU7QUFDckUseUVBQXlFO0FBQ3pFLDJFQUEyRTtBQUMzRSw0RUFBNEU7QUFDNUUsNkVBQTZFO0FBQzdFLG1CQUFtQjtBQUNuQix5RUFBeUU7QUFDekUsT0FBTyxtQ0FBbUMsQ0FBQztBQVMzQyxPQUFPLEVBR0wsc0JBQXNCLEdBRXZCLE1BQU0sd0NBQXdDLENBQUM7QUFDaEQsT0FBTyxFQUNMLGNBQWMsRUFHZCxVQUFVLEVBQ1YsYUFBYSxHQUNkLE1BQU0sb0NBQW9DLENBQUM7QUFDNUMsT0FBTyxFQUNMLE1BQU0sRUFDTixHQUFHLEdBSUosTUFBTSw0QkFBNEIsQ0FBQztBQUNwQyxPQUFPLEVBRUwsS0FBSyxHQUNOLE1BQU0sOEJBQThCLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBTaWRlLWVmZmVjdCBpbXBvcnQ6IGVuc3VyZSBgd29ybGQudHNgIGlzIGxvYWRlZCBzbyBpdHMgbW9kdWxlLWxvYWRcbi8vIGBnbG9iYWxUaGlzW0dldFdvcmxkRm5LZXldID8/PSBnZXRXb3JsZGAgcmVnaXN0cmF0aW9uIGZpcmVzIGJlZm9yZSBhbnlcbi8vIGhvc3Qgcm91dGUgcmVhY2hlcyBgZ2V0V29ybGRMYXp5KClgLiBXaXRob3V0IHRoaXMsIHdlYnBhY2svdHVyYm9wYWNrIGNhblxuLy8gdHJlZS1zaGFrZSBgd29ybGQudHNgIG91dCBvZiByb3V0ZXMgdGhhdCBvbmx5IHVzZSBgc3RhcnRgLiBSZXNvbHZlZCB0byBhblxuLy8gZW1wdHkgc3R1YiB2aWEgdGhlIGB3b3JrZmxvd2AgZXhwb3J0IGNvbmRpdGlvbiBpbiBWTS9zdGVwIGJ1bmRsZXMsIHNvIHRoaXNcbi8vIHN0YXlzIGhvc3Qtb25seS5cbi8vIFNlZSBgQHdvcmtmbG93L2NvcmUvc3JjL3J1bnRpbWUvd29ybGQtaW5pdC50c2AgZm9yIHRoZSBmdWxsIHJhdGlvbmFsZS5cbmltcG9ydCAnQHdvcmtmbG93L2NvcmUvcnVudGltZS93b3JsZC1pbml0JztcblxuZXhwb3J0IHR5cGUge1xuICBDYW5jZWxSdW5PcHRpb25zLFxuICBFdmVudCxcbiAgU3RvcFNsZWVwT3B0aW9ucyxcbiAgU3RvcFNsZWVwUmVzdWx0LFxuICBXb3JrZmxvd1J1bixcbn0gZnJvbSAnQHdvcmtmbG93L2NvcmUvcnVudGltZSc7XG5leHBvcnQge1xuICB0eXBlIFJ1bkNvbXBsZXRlZEhvb2tQYXJhbXMsXG4gIHR5cGUgUnVuRmFpbGVkSG9va1BhcmFtcyxcbiAgcmVnaXN0ZXJMaWZlY3ljbGVIb29rcyxcbiAgdHlwZSBXb3JrZmxvd0xpZmVjeWNsZUhvb2tzLFxufSBmcm9tICdAd29ya2Zsb3cvY29yZS9ydW50aW1lL2xpZmVjeWNsZS1ob29rcyc7XG5leHBvcnQge1xuICBnZXRIb29rQnlUb2tlbixcbiAgdHlwZSBIb29rLFxuICB0eXBlIFJlc3VtZWRIb29rLFxuICByZXN1bWVIb29rLFxuICByZXN1bWVXZWJob29rLFxufSBmcm9tICdAd29ya2Zsb3cvY29yZS9ydW50aW1lL3Jlc3VtZS1ob29rJztcbmV4cG9ydCB7XG4gIGdldFJ1bixcbiAgUnVuLFxuICB0eXBlIFdvcmtmbG93UmVhZGFibGVTdHJlYW0sXG4gIHR5cGUgV29ya2Zsb3dSZWFkYWJsZVN0cmVhbU9wdGlvbnMsXG4gIHR5cGUgV29ya2Zsb3dSdW5Xcml0YWJsZVN0cmVhbU9wdGlvbnMsXG59IGZyb20gJ0B3b3JrZmxvdy9jb3JlL3J1bnRpbWUvcnVuJztcbmV4cG9ydCB7XG4gIHR5cGUgU3RhcnRPcHRpb25zLFxuICBzdGFydCxcbn0gZnJvbSAnQHdvcmtmbG93L2NvcmUvcnVudGltZS9zdGFydCc7XG4iXX0=

package/docs/api-reference/vitest/index.mdx

@@ -5,6 +5,18 @@ description: Vitest plugin and test helpers for integration testing workflows in
 
 The `@workflow/vitest` package provides a Vitest plugin and test helpers for running full workflow integration tests in-process, no server required.
 
+## Installation
+
+```package-install
+npm i -D @workflow/vitest@beta
+```
+
+<Callout type="warn">
+`@workflow/vitest@latest` is still the 4.x line, so a Workflow 5 app has to install the `beta` tag (or pin the matching beta, for example `@workflow/vitest@5.0.0-beta.53`). The package carries its own copy of `@workflow/core` and runs your workflows against it, so it has to move with `workflow`.
+
+`globalSetup` compares the two copies once per run: a different major fails the run with the install command that fixes it, and any other difference logs a warning. Set [`WORKFLOW_VITEST_VERSION_CHECK=off`](/docs/configuration/build-and-diagnostics#workflow_vitest_version_check) to skip the check.
+</Callout>
+
 ## Plugin
 
 ### `workflow()`
@@ -108,6 +120,53 @@ Tears down the workflow test world. Clears the global world and closes the Local
 | `dataDir` | `string` | `<rootDir>/.workflow-data` | Directory for workflow runtime data written by the test world. Relative paths resolve against `cwd`. |
 | `outDir` | `string` | `<rootDir>/.workflow-vitest` | Directory for generated workflow and step bundles. Relative paths resolve against `cwd`. |
 
+## Workflow references
+
+The test build writes the same `manifest.json` the other Workflow builders write into `outDir`. These helpers read it, so a test can name a workflow instead of hand-writing the generated `workflow//...` id. Importing the workflow function is still preferable when a test can do it, because it keeps the argument and return types.
+
+### `getWorkflowRef()`
+
+Looks up one workflow in the test build and returns it in the shape [`start()`](/docs/api-reference/workflow-api/start) accepts.
+
+```typescript
+import { getWorkflowRef } from "@workflow/vitest"; // [!code highlight]
+import { start } from "workflow/api";
+
+const run = await start(getWorkflowRef("approvalWorkflow"), ["doc-1"]); // [!code highlight]
+```
+
+`query` is an exported workflow name, or a file-qualified name when the same name appears in more than one file: `getWorkflowRef("workflows/approval.ts#approvalWorkflow")`. The file part also matches by path suffix, so `"approval.ts#approvalWorkflow"` resolves the same entry.
+
+**Parameters:**
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `query` | `string` | Workflow name, or `<file>#<name>` |
+
+**Returns:** [`WorkflowRef`](#workflowref).
+
+**Throws** when the manifest is missing (the plugin or `buildWorkflowTests()` has not run), when nothing matches, or when the name is ambiguous. The message lists the workflows the build contains.
+
+### `listWorkflowRefs()`
+
+Returns every workflow in the test build, sorted by file and then name.
+
+```typescript
+import { listWorkflowRefs } from "@workflow/vitest"; // [!code highlight]
+
+const names = listWorkflowRefs().map((ref) => ref.name); // [!code highlight]
+```
+
+**Returns:** [`WorkflowRef`](#workflowref)`[]`.
+
+### `WorkflowRef`
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | Exported name of the workflow function |
+| `file` | `string` | Project-relative path of the file it was compiled from |
+| `workflowId` | `string` | Generated workflow id, the field `start()` reads |
+
 ## Test helpers
 
 ### `waitForSleep()`

package/docs/api-reference/workflow/set-attributes.mdx

@@ -54,7 +54,9 @@ export async function cleanupAttributes() {
 
 Attribute keys must be 1-256 characters, values must be strings up to 256 bytes, and each run can have up to 64 attributes. Keys that start with `$` are reserved for framework and library code.
 
-Validation errors throw [`FatalError`](/docs/api-reference/workflow/fatal-error) and fail the run before an attribute write is attempted.
+Each call's complete `attr_set` event data must also fit in **8192 UTF-8 JSON bytes (8KiB)**. This includes the change keys and values, JSON escaping and structure, writer metadata (including the step ID and attempt for step calls), and the reserved-key option when enabled. It is not a limit on values alone. Split large updates into smaller calls; updates across multiple calls are not atomic and still share the 64-attribute per-run limit.
+
+Validation errors reject `setAttributes` with [`FatalError`](/docs/api-reference/workflow/fatal-error) before a new attribute write is attempted. Catch the error if the metadata is best-effort; an uncaught error fails the workflow or step. Previously persisted attribute events remain replayable.
 
 Calls from both workflow and step bodies append a native `attr_set` event, which the World materializes onto `run.attributes`. Workflow-originated events record a workflow writer; step-originated events record the originating step ID and attempt.
 

package/docs/api-reference/workflow-api/index.mdx

@@ -25,6 +25,9 @@ The `workflow/api` package provides runtime functions to inspect runs, start new
     <Card href="/docs/api-reference/workflow-api/get-run" title="getRun()">
         Get workflow run status and metadata without waiting for completion.
     </Card>
+    <Card href="/docs/api-reference/workflow-api/register-lifecycle-hooks" title="registerLifecycleHooks()">
+        Observe run completions and failures with global handlers.
+    </Card>
 </Cards>
 
 <Callout type="info">

package/docs/api-reference/workflow-api/register-lifecycle-hooks.mdx

@@ -0,0 +1,85 @@
+---
+title: registerLifecycleHooks
+description: Register global handlers that observe workflow runs completing or failing.
+type: reference
+summary: Use registerLifecycleHooks to observe run completions and failures from one central place.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/observability/lifecycle-hooks
+  - /docs/api-reference/workflow-api/get-run
+---
+
+Registers global workflow lifecycle handlers, invoked by the runtime on the compute that records a run's terminal transition. Use it for best-effort centralized reporting, such as forwarding failed runs to Sentry, without wrapping each workflow body.
+
+Register early in the process lifecycle (in Next.js, `instrumentation.ts`) so handlers exist before the first run finishes. See the [lifecycle hooks guide](/docs/observability/lifecycle-hooks) for semantics and a full Sentry example.
+
+```typescript title="instrumentation.ts" lineNumbers
+export async function register() {
+  if (process.env.NEXT_RUNTIME === "nodejs") {
+    const { registerLifecycleHooks } = await import("workflow/api");
+
+    registerLifecycleHooks({
+      async onRunCompleted({ run, workflowName }) {
+        console.log(`Run ${run.runId} (${workflowName}) completed`);
+      },
+      async onRunFailed({ run, workflowName, error }) {
+        console.error(
+          `Run ${run.runId} (${workflowName}) failed (${error.errorCode})`,
+          error.cause
+        );
+      },
+    });
+  }
+}
+```
+
+Keep the dynamic import inside the `NEXT_RUNTIME === "nodejs"` guard. Next.js also compiles `instrumentation.ts` for the Edge runtime. A top-level static import of `workflow/api` pulls Node.js-only dependencies into that compilation and breaks webpack Edge builds, even if the registration call is guarded.
+
+## API Signature
+
+### Parameters
+
+<TSDoc
+definition={`
+import { registerLifecycleHooks } from "workflow/api";
+export default registerLifecycleHooks;`}
+showSections={["parameters"]}
+/>
+
+### Returns
+
+Returns a function that unregisters these hooks.
+
+## Handlers
+
+Both handlers receive a `workflowName` string and a lazily hydrated [`Run`](/docs/api-reference/workflow-api/get-run) instance. Use the `workflowName` parameter to filter without a backend read; `run.runId` also requires no read. Accessors such as `run.workflowName`, `run.status`, and `run.returnValue` still fetch from the backend when used. Lazy access defers those reads rather than eliminating them.
+
+### `onRunCompleted`
+
+Invoked when a workflow run completes successfully.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `params.run` | `Run` | The completed run. |
+| `params.workflowName` | `string` | The machine-readable workflow identifier, such as `workflow//./src/workflows/order//processOrder`. Available without a backend read. |
+
+### `onRunFailed`
+
+Invoked when a workflow run fails terminally (after any retries).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `params.run` | `Run` | The failed run. |
+| `params.workflowName` | `string` | The machine-readable workflow identifier, such as `workflow//./src/workflows/order//processOrder`. Available without a backend read. |
+| `params.error` | `WorkflowRunFailedError` | The failure, in the same shape `run.returnValue` rejects with: `error.errorCode` carries the classification (e.g. `USER_ERROR`) and `error.cause` is the hydrated thrown value. |
+
+`error.cause` is hydrated from the persisted error data, with streamed values loaded lazily when consumed. Abort signals reflect their persisted state without live subscriptions. If hydration fails, the cause is a generic `Error`, matching `run.returnValue`'s fallback. In `onRunFailed`, `run.returnValue` rejects because the run failed. Use `error.cause` to inspect or report the thrown value instead.
+
+## Behavior
+
+- Handlers run on the host (full Node.js), never inside the workflow VM. Calling `registerLifecycleHooks` from workflow code throws.
+- Handlers are fire-and-forget. They cannot delay or change the run's outcome, and the runtime logs and swallows a throwing handler. On Vercel, `waitUntil` keeps the invocation alive while handlers finish, subject to the invocation's duration limit. On other hosts, handlers run as detached work and may not complete if the host freezes or terminates the process after the response.
+- Delivery is best effort. Each registered handler is invoked at most once by the invocation that writes the terminal event. Callbacks are not retried if they throw or the process dies, so they may never run or may stop before completing. The [event log](/docs/how-it-works/event-sourcing) is the system of record.
+- Handlers fire only on the invocation that wrote the terminal event. Transitions recorded outside your app's compute (e.g. a run cancelled from the CLI or dashboard) do not fire handlers.
+- You can register multiple hook sets, and handlers run in registration order.

package/docs/api-reference/workflow-globals.mdx

@@ -23,7 +23,7 @@ These APIs are available but are **seeded or fixed** to ensure deterministic beh
 | API | Behavior |
 |-----|----------|
 | [`Math.random()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random) | Seeded random number generator: same seed produces the same sequence every replay |
-| [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) / `Date.now()` / `new Date()` | Returns a fixed timestamp that advances with the workflow's logical clock |
+| [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) / `Date.now()` / `new Date()` | Returns the workflow's logical clock: the run's creation time until the first step result, hook payload, hook registration, wait completion or abort reaches the workflow, then the time that event was recorded, advancing as each later one is delivered. Identical on every replay of the same log |
 | [`crypto.getRandomValues()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues) | Seeded: produces deterministic output for a given workflow run |
 | [`crypto.randomUUID()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/randomUUID) | Seeded: produces deterministic UUIDs for a given workflow run |
 | [`crypto.subtle.digest()`](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/digest) | Computed synchronously via `node:crypto` (values are byte-identical to WebCrypto), so the promise settles at a deterministic point during replay |

package/docs/api-reference/workflow-nest/configure-workflow-controller.mdx

@@ -9,7 +9,11 @@ prerequisites:
 
 Configures the output directory that [`WorkflowController`](/docs/api-reference/workflow-nest/workflow-controller) loads the generated workflow bundles (`steps.mjs`, `workflows.mjs`, `webhook.mjs`, `manifest.json`) from.
 
-[`WorkflowModule.forRoot()`](/docs/api-reference/workflow-nest/workflow-module) calls this for you with its resolved `outDir`. Call it yourself only when registering `WorkflowController` manually. The controller's route handlers throw if no directory has been configured.
+<Callout type="warn">
+Deprecated. [`WorkflowModule.forRoot()`](/docs/api-reference/workflow-nest/workflow-module) provides the output directory through dependency injection, which this function predates. It writes process-global state, so two applications in one process (the usual `Test.createTestingModule` setup) overwrite each other's configuration. It is kept only so existing callers keep working.
+</Callout>
+
+`WorkflowModule.forRoot()` still calls this for you, and injected options take precedence over it. Call it yourself only when registering `WorkflowController` without the module. A controller with no configuration at all answers `503` with an explanatory message.
 
 ## Usage
 

package/docs/api-reference/workflow-nest/workflow-controller.mdx

@@ -9,6 +9,10 @@ prerequisites:
 
 NestJS controller that handles the well-known workflow endpoints under `.well-known/workflow/v1`. It dynamically imports the generated workflow bundles and converts between Express/Fastify requests and the Web API `Request`/`Response` objects the workflow runtime expects. Both the Express and Fastify HTTP adapters are supported.
 
+The conversion preserves bytes in both directions: request bodies come from `req.rawBody` when the app is created with `{ rawBody: true }`, from a `Buffer`/string body left by a parser, or read directly from the request stream when no parser claimed the content type. Responses are written as bytes, and every `set-cookie` value is kept. See [Raw request bodies](/docs/getting-started/nestjs#raw-request-bodies).
+
+Handlers take `@Res()`, so the application's interceptors and exception filters do not wrap these routes. That is deliberate: the queue and third-party webhook senders key off the exact status and body the workflow runtime produces.
+
 [`WorkflowModule.forRoot()`](/docs/api-reference/workflow-nest/workflow-module) registers this controller automatically. You only register it yourself if you are not using `WorkflowModule`.
 
 ## Usage
@@ -35,6 +39,8 @@ export class AppModule {}
 
 | Route | Method | Description |
 | --- | --- | --- |
-| `/.well-known/workflow/v1/flow` | `POST` | Executes workflow and step work items via the combined handler in `workflows.mjs` (step registrations are imported from `steps.mjs` first). |
+| `/.well-known/workflow/v1/flow` | `POST`, `GET`, `HEAD`, `OPTIONS` | Executes workflow and step work items via the combined handler in `workflows.mjs` (step registrations are imported from `steps.mjs` first). `HEAD` is what local port detection probes to identify a workflow server, so all four methods are served. |
 | `/.well-known/workflow/v1/webhook/:token` | Any | Forwards webhook requests to the handler in `webhook.mjs`. |
 | `/.well-known/workflow/v1/manifest.json` | `GET` | Serves the workflow manifest. Responds with `404` unless the `WORKFLOW_PUBLIC_MANIFEST=1` environment variable is set. |
+
+A route whose bundle cannot be loaded answers `503` with a message naming the missing file and the build command that produces it, rather than surfacing a raw `ERR_MODULE_NOT_FOUND`.

package/docs/api-reference/workflow-nest/workflow-module.mdx

@@ -46,7 +46,29 @@ export class AppModule {}
 
 #### `forRoot(options?)`
 
-Configures the module and returns a NestJS `DynamicModule` registered as `global`. It calls [`configureWorkflowController`](/docs/api-reference/workflow-nest/configure-workflow-controller) with the resolved output directory, and (unless `skipBuild` is set) creates a [`NestLocalBuilder`](/docs/api-reference/workflow-nest/nest-local-builder) that builds the workflow bundles when the module initializes.
+Configures the module and returns a NestJS `DynamicModule` registered as `global`. It provides the resolved options under the `WORKFLOW_MODULE_OPTIONS` token, and (unless `skipBuild` is set) creates a [`NestLocalBuilder`](/docs/api-reference/workflow-nest/nest-local-builder) that builds the workflow bundles when the module initializes.
+
+#### `forRootAsync(options)`
+
+Same as `forRoot`, with the options produced by a factory so they can come from other providers.
+
+{/* @skip-typecheck - config snippet, WorkflowModule imported above */}
+
+```typescript title="src/app.module.ts" lineNumbers
+WorkflowModule.forRootAsync({
+  imports: [ConfigModule],
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({
+    basePath: config.get("API_PREFIX"),
+  }),
+});
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `imports` | `unknown[]` | Optional. Modules whose exported providers the factory injects. |
+| `inject` | `unknown[]` | Optional. Providers passed to `useFactory`, in order. |
+| `useFactory` | `(...args) => WorkflowModuleOptions \| Promise<WorkflowModuleOptions>` | Returns the module options. |
 
 ### Parameters
 
@@ -60,15 +82,53 @@ Extends [`NestBuilderOptions`](/docs/api-reference/workflow-nest/nest-local-buil
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
-| `skipBuild` | `boolean` | `false` | Skip building workflow bundles on startup. Useful in production when the bundles are pre-built. |
+| `skipBuild` | `boolean` | `true` when `VERCEL` is set, else `false` | Skip building workflow bundles on startup. The bundles must already exist; startup fails with an explicit error if they do not. |
+| `basePath` | `string` | adopted from `app.setGlobalPrefix()` | Route prefix the workflow endpoints are served under, applied to generated callback and webhook URLs. Set it when a reverse proxy mounts the app on a sub-path NestJS cannot see. |
+| `manageWorldLifecycle` | `boolean` | `false` | Start the target World's background workers with the app and close them on shutdown. Required for self-hosted Worlds, which otherwise never pick up runs. |
+| `preloadBundles` | `boolean` | `false` when `VERCEL` is set, else `true` | Load the generated bundles during startup instead of on the first request. On Vercel, dedicated functions serve the bundles, so there is nothing to preload. |
 | `workingDir` | `string` | `process.cwd()` | Working directory for the NestJS application. |
 | `dirs` | `string[]` | `['src']` | Directories to scan for workflow files. |
 | `outDir` | `string` | `'.nestjs/workflow'` (relative to `workingDir`) | Output directory for generated workflow bundles. |
-| `watch` | `boolean` | `false` | Enable watch mode for development. |
+| `watch` | `boolean` | `false` | Deprecated and ignored. Watch mode is not implemented for this builder. Use `nest start --watch`, which re-runs the startup build. |
 | `moduleType` | `'es6' \| 'commonjs'` | `'es6'` | SWC module compilation type. Set to `'commonjs'` if your NestJS project compiles to CommonJS (CJS) through SWC. |
 | `distDir` | `string` | `'dist'` | Directory where NestJS compiles `.ts` source files to `.js` (relative to `workingDir`). Used when `moduleType` is `'commonjs'`. Should match the `outDir` in your `tsconfig.json`. |
 | `sourcemap` | `boolean \| 'inline' \| 'linked' \| 'external' \| 'both'` | `'inline'` (dev) / `false` (prod) | Controls source maps on generated workflow bundles. Defaults to `'inline'` in development and `false` in production. Can also be set via the `WORKFLOW_SOURCEMAP` environment variable. |
 
 ### Returns
 
-`forRoot()` returns a `DynamicModule` to include in the `imports` array of your root module.
+`forRoot()` and `forRootAsync()` return a `DynamicModule` to include in the `imports` array of your root module.
+
+## Injecting the resolved options
+
+Both factories export the resolved options under `WORKFLOW_MODULE_OPTIONS`:
+
+{/* @skip-typecheck - NestJS decorators require special TypeScript config */}
+
+```typescript title="src/some.service.ts" lineNumbers
+import { Inject, Injectable } from "@nestjs/common";
+import {
+  WORKFLOW_MODULE_OPTIONS,
+  type WorkflowModuleOptions,
+} from "workflow/nest";
+
+@Injectable()
+export class SomeService {
+  constructor(
+    @Inject(WORKFLOW_MODULE_OPTIONS)
+    private readonly options: WorkflowModuleOptions
+  ) {}
+}
+```
+
+The older `WORKFLOW_OPTIONS` token resolves to the same value and is kept for compatibility.
+
+## Lifecycle
+
+| Hook | Behaviour |
+| --- | --- |
+| `onModuleInit` | Reconciles the base path against `app.setGlobalPrefix()`, builds the bundles (or verifies they exist when `skipBuild` is set), optionally starts the World, and preloads the bundles. |
+| `onApplicationShutdown` | Closes the World when `manageWorldLifecycle` is set. Call `app.enableShutdownHooks()` so this runs on a signal. |
+
+<Callout type="warn">
+Workflows and steps run outside the NestJS injector, so providers cannot be injected into `"use workflow"` or `"use step"` code. See [NestJS dependency injection is not available in workflows and steps](/docs/getting-started/nestjs#nestjs-dependency-injection-is-not-available-in-workflows-and-steps).
+</Callout>

package/docs/api-reference/workflow-runtime/world/storage.mdx

@@ -189,12 +189,15 @@ a normal return, not an error, and a missing run throws
 
 ```typescript lineNumbers
 const result = await world.runs.list({ // [!code highlight]
+  status: "running", // [!code highlight]
   pagination: { cursor },
 }); // [!code highlight]
 ```
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
+| `params.workflowName` | `string` | Only return runs of this workflow |
+| `params.status` | `WorkflowRunStatus \| WorkflowRunStatus[]` | Only return runs in this status. Pass an array to match any of the listed statuses; an empty array matches no runs. `@workflow/world-vercel` accepts a single status only and throws `WorkflowWorldError` (`INVALID_ARGUMENT`) for an array |
 | `params.pagination.cursor` | `string` | Cursor for the next page |
 | `params.resolveData` | `'all' \| 'none'` | Whether to include input/output data |
 
@@ -219,7 +222,7 @@ To cancel a batch in one call, a world may implement the optional `runs.cancelMa
 | Field | Type | Description |
 |-------|------|-------------|
 | `runId` | `string` | Unique run identifier |
-| `status` | `string` | `'running'`, `'completed'`, `'failed'`, `'cancelled'` |
+| `status` | `string` | `'pending'`, `'running'`, `'completed'`, `'failed'`, `'cancelled'` |
 | `workflowName` | `string` | Machine-readable workflow identifier |
 | `input` | `any` | Workflow input data (when `resolveData: 'all'`) |
 | `output` | `any` | Workflow output data (when `resolveData: 'all'`) |

package/docs/configuration/build-and-diagnostics.mdx

@@ -53,6 +53,15 @@ Accepted values:
 - The SDK's own runtime serde classes (for example, `Run`) stay registered because they are reached through a seeded entry point, and imports *within* `node_modules` are still followed.
 - Explicit framework config wins over this environment variable.
 
+## Testing
+
+### `WORKFLOW_VITEST_VERSION_CHECK`
+
+- Default: enabled
+- Read by [`@workflow/vitest`](/docs/api-reference/vitest) in `globalSetup`, once per test run.
+- The plugin builds and runs your workflows against the copy of `@workflow/core` it was installed with. Before building, it compares that copy with the one your app resolves: a different major fails the run with the install command that fixes it, and any other difference logs a warning.
+- Set `off` (or `0` / `false`) to skip the check, for example in a setup that resolves two copies on purpose.
+
 ## Development diagnostics
 
 ### `WORKFLOW_DEV_HMR_LOGS`

package/docs/configuration/worlds.mdx

@@ -27,6 +27,8 @@ Broader signals are deliberately ignored. `vercel env pull` writes `VERCEL=1` in
 
 A deployment that pins `WORKFLOW_TARGET_WORLD=local` warns at startup and fails on its first write, because a Vercel deployment's filesystem is read-only.
 
+A deployment can land on the Local World without pinning anything, and without that warning, if the project has cleared **Enable access to System Environment Variables** under **Settings**, then **Environment Variables**. That checkbox is what makes Vercel expose `VERCEL_DEPLOYMENT_ID` to your build and your functions; with it off, there is no signal to detect, so detection and the warning both see an ordinary non-Vercel process. See [System environment variables](/worlds/vercel#system-environment-variables) for how to confirm and fix it.
+
 Set `WORKFLOW_TARGET_WORLD` only when you want to use a custom or self-hosted World:
 
 - `local`: Alias for `@workflow/world-local`.
@@ -197,7 +199,7 @@ The Vercel World is configured automatically inside Vercel deployments. The plat
 
 Most applications should not set `WORKFLOW_VERCEL_*` variables on Vercel. They configure tooling that talks to a Vercel Workflow project from outside a deployment, such as the Workflow CLI, the web user interface (UI), continuous integration (CI), or tests. The runtime warns if these variables are set in a deployed Vercel Function because they do not control runtime configuration there.
 
-Platform-provided values such as `VERCEL_DEPLOYMENT_ID`, `VERCEL_PROJECT_ID`, and `VERCEL_DEPLOYMENT_KEY` are read by the runtime inside Vercel deployments. Do not set them yourself.
+Platform-provided values such as `VERCEL_DEPLOYMENT_ID`, `VERCEL_PROJECT_ID`, and `VERCEL_DEPLOYMENT_KEY` are read by the runtime inside Vercel deployments. Do not set them yourself; keep [system environment variables](/worlds/vercel#system-environment-variables) enabled for the project so that Vercel provides them.
 
 ### `token`
 

package/docs/deploying.mdx

@@ -51,6 +51,17 @@ vercel deploy
 
 <FluidComputeCallout />
 
+<Callout type="warn">
+  **Enable access to System Environment Variables before deploying.** Workflow
+  recognizes a Vercel deployment by `VERCEL_DEPLOYMENT_ID`, which Vercel exposes
+  to your build and your functions only when the **Enable access to System
+  Environment Variables** checkbox is selected under **Settings**, then
+  **Environment Variables**, in your project. With it cleared, the deployment
+  falls back to the Local World and every run fails on the read-only
+  filesystem. See
+  [System environment variables](/worlds/vercel#system-environment-variables).
+</Callout>
+
 <Callout>
   Learn more about the [Vercel World](/worlds/vercel) and its capabilities, including [multi-region](/worlds/vercel#multi-region).
 </Callout>

package/docs/getting-started/nestjs.mdx

@@ -398,15 +398,11 @@ export default async function handler(req: express.Request, res: express.Respons
 }
 ```
 
-Skip the in-process build on Vercel (the bundles are pre-built) by passing `skipBuild` when
-`VERCEL` is set:
+No module change is needed for the in-process build: `skipBuild` defaults to `true` when the
+`VERCEL` environment variable is set, because the Build Output already contains the bundles and
+the deployed filesystem is read-only.
 
-{/* @skip-typecheck - config snippet, WorkflowModule imported above */}
-```typescript title="src/app.module.ts"
-WorkflowModule.forRoot({ skipBuild: Boolean(process.env.VERCEL) });
-```
-
-Then set your build command so the Build Output is produced after `nest build`:
+Set your build command so the Build Output is produced after `nest build`:
 
 ```json title="package.json" lineNumbers
 {
@@ -440,7 +436,9 @@ WorkflowModule.forRoot({
   // Output directory for generated bundles (default: '.nestjs/workflow')
   outDir: '.nestjs/workflow',
 
-  // Skip building in production when bundles are pre-built
+  // Skip building when bundles are pre-built with `workflow-nest build`
+  // (default: true when VERCEL is set, false otherwise). Startup fails if the
+  // bundles are missing.
   skipBuild: false,
 
   // SWC module type: 'es6' (default) or 'commonjs'
@@ -460,9 +458,187 @@ WorkflowModule.forRoot({
   // size limit) at the cost of stack traces pointing at generated code.
   // Can also be set via the WORKFLOW_SOURCEMAP environment variable.
   sourcemap: 'inline',
+
+  // Route prefix the workflow endpoints are served under. Leave unset to adopt
+  // app.setGlobalPrefix() automatically; set it when a reverse proxy mounts the
+  // app on a sub-path NestJS does not know about. See "Global prefixes" below.
+  basePath: '/api',
+
+  // Start the target World's background workers with the app and close them on
+  // shutdown. Self-hosted Worlds (for example @workflow/world-postgres) need
+  // this or runs are created and never picked up. Leave off on Vercel.
+  manageWorldLifecycle: false,
+
+  // Load the generated bundles during startup instead of on the first request
+  // (default: true, or false when VERCEL is set because dedicated functions
+  // serve the bundles there).
+  preloadBundles: true,
 });
 ```
 
+Options can also come from other providers with `forRootAsync`:
+
+{/*@skip-typecheck - Configuration snippet, imports shown above*/}
+
+```typescript
+WorkflowModule.forRootAsync({
+  imports: [ConfigModule],
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({
+    basePath: config.get('API_PREFIX'),
+  }),
+});
+```
+
+---
+
+## Global prefixes and sub-paths
+
+`app.setGlobalPrefix()` moves the workflow routes. The SDK has to generate its
+queue callback and webhook URLs under the same prefix, or every delivery 404s and
+runs stay `pending`.
+
+`WorkflowModule` reads the global prefix during startup and adopts it, so this
+works with no configuration:
+
+{/*@skip-typecheck - Bootstrap snippet*/}
+
+```typescript
+const app = await NestFactory.create(AppModule);
+app.setGlobalPrefix('api'); // workflow URLs become /api/.well-known/workflow/v1/...
+await app.listen(3000);
+```
+
+Set `basePath` explicitly when the prefix is applied outside NestJS, for example
+by a reverse proxy that strips it before the request reaches your app. An
+explicit `basePath` wins over the global prefix, and a disagreement between the
+two is logged at startup.
+
+For Vercel, pass the same value to the build so the deployed queue-consumer
+function generates matching URLs:
+
+```bash
+workflow-nest build --vercel --base-path /api
+```
+
+<Callout type="warn">
+`app.enableVersioning()` moves the workflow routes the same way, and is not
+handled automatically. Exclude the workflow controller from versioning, or mount
+it where the SDK expects it.
+</Callout>
+
+---
+
+## Raw request bodies
+
+The workflow routes are a byte pipe. A webhook that verifies a signature over its
+raw body (Stripe, GitHub, Shopify, Slack) only works if the bytes the sender
+signed reach the workflow unchanged, and a body parser that has already turned
+the request into an object destroys them.
+
+Create the app with `rawBody` so the original bytes stay available:
+
+{/*@skip-typecheck - Bootstrap snippet*/}
+
+```typescript
+const app = await NestFactory.create(AppModule, { rawBody: true });
+```
+
+Without it, `@workflow/nest` falls back to re-serializing the parsed body with
+`JSON.stringify` and logs a warning once. That changes whitespace and key order,
+so signature verification fails.
+
+Content types no body parser claims (XML, `application/x-www-form-urlencoded`
+without the parser registered, custom media types) are read straight from the
+request stream and need no configuration.
+
+<Callout type="info">
+On Vercel the webhook route is served by its own function rather than by your
+NestJS app, so this only affects self-hosted deployments.
+</Callout>
+
+---
+
+## NestJS dependency injection is not available in workflows and steps
+
+Workflows and steps do not run inside your NestJS application. They are compiled
+into separate bundles, so **the Nest injector, your providers, and anything
+built on the request context are out of reach from `"use workflow"` and
+`"use step"` code.**
+
+Concretely, none of these work inside a step:
+
+- injecting a provider, or resolving one with `app.get(MyService)`
+- `@Injectable()` classes reached through a module-level reference to the app
+- request-scoped providers, and `AsyncLocalStorage` context such as `nestjs-cls`
+- guards, interceptors, pipes, and filters
+- the Nest `Logger`
+
+Two mechanics cause this, and neither has a workaround:
+
+1. A step's bundle gets **its own copy** of any application file it imports.
+   Module-level state is therefore duplicated, and a class imported into a step
+   is a different class object from the one your module registered. Nest uses the
+   class itself as the injection token, so `app.get(MyService)` from a step
+   raises `UnknownElementException` even when it can reach the app.
+2. On Vercel, workflows and steps run in the queue-consumer function, a separate
+   function from the one serving your NestJS app. There is no shared process to
+   reach into.
+
+Write steps as plain functions over their arguments, and keep the wiring in your
+controllers and providers:
+
+{/*@skip-typecheck - Illustrates the pattern, not a complete app*/}
+
+```typescript
+// A step takes what it needs as arguments and builds its own clients.
+async function chargeCustomer(customerId: string, cents: number) {
+  'use step';
+  const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
+  return await stripe.charges.create({ customer: customerId, amount: cents });
+}
+
+// The controller stays a normal Nest controller with normal DI.
+@Controller('billing')
+export class BillingController {
+  constructor(private readonly customers: CustomerService) {}
+
+  @Post('charge')
+  async charge(@Body() body: { id: string }) {
+    const customer = await this.customers.find(body.id);
+    // Pass plain, serializable values into the workflow.
+    await start(billingWorkflow, [customer.id, customer.planCents]);
+    return { started: true };
+  }
+}
+```
+
+Configuration a step needs should come from the environment rather than
+`ConfigService`, and shared logic should live in plain modules that a step can
+import without pulling in `@nestjs/common`.
+
+<Callout type="info">
+Importing a file that uses `@nestjs/common` into a step is supported and builds
+correctly, it simply gives you a class with no injected dependencies. Prefer
+plain functions so the intent is clear.
+</Callout>
+
+---
+
+## Production checklist
+
+- Run `workflow-nest build` in your build step and set `skipBuild: true`, or
+  leave `skipBuild` unset so the bundles are built during startup. With
+  `skipBuild` set and no bundles present, startup fails with an explicit error
+  rather than serving broken workflow routes.
+- Create the app with `{ rawBody: true }` if you receive signed webhooks.
+- Set `basePath` (or rely on the adopted global prefix) so generated URLs match
+  the routes NestJS serves.
+- Set `manageWorldLifecycle: true` for a self-hosted World, and call
+  `app.enableShutdownHooks()` so the World is closed on a signal.
+- `skipBuild` defaults to `true` when the `VERCEL` environment variable is set,
+  so no Vercel-specific branch is needed in your module configuration.
+
 ## Troubleshooting
 
 ### `start()` says it received an invalid workflow function

package/docs/observability/attributes.mdx

@@ -57,6 +57,8 @@ export async function cleanupAttributes() {
 
 Attribute keys must be 1-256 characters, values must be strings up to 256 bytes, and each run can have up to 64 attributes. Keys that start with `$` are reserved for framework and library code.
 
+Each `setAttributes` call also writes one `attr_set` event, and that event's complete data (keys, values, and writer metadata) must fit in 8192 UTF-8 JSON bytes (8KiB). Split large updates across several calls; the calls still share the 64-attribute limit. A call that exceeds a limit rejects with [`FatalError`](/docs/api-reference/workflow/fatal-error) before anything is written, so catch it when the metadata is best-effort.
+
 ## Reserved keys
 
 When `start()` is called from inside a running workflow or step, the new run is automatically tagged with two reserved attributes:

package/docs/observability/lifecycle-hooks.mdx

@@ -0,0 +1,93 @@
+---
+title: Lifecycle Hooks
+description: Register global handlers that observe workflow runs completing or failing, for centralized reporting to services like Sentry.
+type: guide
+summary: Observe run completions and failures from a single place with registerLifecycleHooks.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/observability
+  - /docs/observability/tracing
+  - /docs/errors
+---
+
+Lifecycle hooks let you register global handlers that observe workflow runs completing or failing on your app's compute. They can observe even the failures that never reach a `try/catch` in workflow code, such as a replay timing out or a run exhausting its queue deliveries. Use them for best-effort centralized error reporting, such as forwarding failed runs to Sentry without wrapping each workflow body.
+
+## Registering hooks
+
+Call `registerLifecycleHooks` from `workflow/api` early in your application's lifecycle, so the handlers exist before the first run finishes. In Next.js, [`instrumentation.ts`](https://nextjs.org/docs/app/building-your-application/optimizing/instrumentation) is the natural place; in any other app, any module that loads at startup works.
+
+```typescript title="instrumentation.ts" lineNumbers
+export async function register() {
+  if (process.env.NEXT_RUNTIME === "nodejs") {
+    const { registerLifecycleHooks } = await import("workflow/api")
+
+    registerLifecycleHooks({
+      async onRunCompleted({ run, workflowName }) {
+        console.log(`Run ${run.runId} (${workflowName}) completed`)
+      },
+      async onRunFailed({ run, workflowName, error }) {
+        console.error(
+          `Run ${run.runId} (${workflowName}) failed with ${error.errorCode}:`,
+          error.cause
+        )
+      },
+    })
+  }
+}
+```
+
+Keep the dynamic `workflow/api` import inside the `NEXT_RUNTIME === "nodejs"` guard. Next.js also compiles `instrumentation.ts` for the Edge runtime. A top-level static import pulls Node.js-only dependencies into that compilation and breaks webpack Edge builds, even if the registration call is guarded.
+
+`registerLifecycleHooks` returns an unregister function. You can register multiple hook sets, and handlers run in registration order.
+
+## Handler parameters
+
+Both handlers receive a `workflowName` string and the [`Run`](/docs/api-reference/workflow-api/get-run) instance for the transitioned run. `workflowName` is the machine-readable workflow identifier, such as `workflow//./src/workflows/order//processOrder`. Use this parameter to filter runs without a backend read. `run.runId` is also available without a read.
+
+The `Run` instance hydrates lazily. Accessors such as `run.workflowName`, `run.status`, and `run.returnValue` still fetch from the backend when used. Lazy access defers those reads; it does not make them free.
+
+`onRunFailed` additionally receives the failure as a `WorkflowRunFailedError`, the same shape `run.returnValue` rejects with:
+
+- `error.errorCode`: the failure classification (`USER_ERROR`, `RUNTIME_ERROR`, `MAX_DELIVERIES_EXCEEDED`, and more). See [error codes](/docs/errors) for the full list.
+- `error.cause`: the thrown value hydrated from the persisted error data, with registered Error subclass identity, message, stack, and cause chain preserved. Streamed values load lazily when consumed, and abort signals reflect their persisted state without live subscriptions. If hydration fails, the cause is a generic `Error`, matching `run.returnValue`'s fallback. Any JavaScript value can be thrown, so this is typed `unknown`.
+
+In `onRunFailed`, `run.returnValue` rejects because the run failed. Use `error.cause` to inspect or report the thrown value instead of awaiting `run.returnValue`.
+
+## Reporting failed runs to Sentry
+
+This example reports failures for workflows named `processOrder`. Remove the filter to report failures from all workflows.
+
+```typescript title="instrumentation.ts" lineNumbers
+export async function register() {
+  if (process.env.NEXT_RUNTIME === "nodejs") {
+    const { registerLifecycleHooks } = await import("workflow/api")
+    const Sentry = await import("@sentry/nextjs")
+
+    Sentry.init({ dsn: process.env.SENTRY_DSN })
+
+    registerLifecycleHooks({
+      async onRunFailed({ run, workflowName, error }) {
+        if (!workflowName.endsWith("//processOrder")) return
+
+        Sentry.captureException(error.cause ?? error, {
+          tags: {
+            workflowRunId: run.runId,
+            workflowName,
+            errorCode: error.errorCode,
+          },
+        })
+        await Sentry.flush(2000)
+      },
+    })
+  }
+}
+```
+
+## How handlers behave
+
+- **Host-only.** Handlers run with full Node.js access, never inside the workflow's sandboxed VM. Calling `registerLifecycleHooks` from workflow code throws.
+- **Fire-and-forget.** Handlers cannot delay or change the run's outcome. The runtime logs and swallows a throwing handler, and the remaining handlers still run. On Vercel, `waitUntil` keeps the invocation alive while handlers finish, subject to the invocation's duration limit. On other hosts, handlers run as detached work. If the host freezes or terminates the process after the response, handlers may not complete.
+- **Best-effort delivery.** Each registered handler is invoked at most once by the invocation that writes the terminal event. For a failure, this happens after any workflow or step retries are exhausted. Callbacks are not retried if they throw or the process dies, so a callback may never run or may stop before completing. The [event log](/docs/how-it-works/event-sourcing) is the system of record, not lifecycle callbacks.
+- **Fires where the transition is recorded.** Terminal transitions recorded outside your app's compute do **not** fire handlers. For example, when you cancel a run from the CLI or the Vercel dashboard, the backend writes that transition, so no handler runs.
+- **Register everywhere your workflows run.** The terminal write can happen in any function invocation that processes the run's queue messages, so registration must run at startup in every instance of the app (which `instrumentation.ts` guarantees).

package/docs/observability/meta.json

@@ -1,4 +1,4 @@
 {
   "title": "Observability",
-  "pages": ["tracing", "attributes", "retention"]
+  "pages": ["tracing", "attributes", "retention", "lifecycle-hooks"]
 }

package/docs/testing/index.mdx

@@ -85,7 +85,19 @@ Unit testing works well for individual steps. A workflow that only calls steps c
 For workflows that rely on runtime features like [hooks](/docs/foundations/hooks), [webhooks](/docs/foundations/hooks#understanding-webhooks), [`sleep()`](/docs/api-reference/workflow/sleep), or error retries, you need to test against a real workflow setup. The `@workflow/vitest` plugin handles everything automatically: it compiles your workflow directives, builds the runtime bundles, and executes workflows entirely in-process. No server required.
 
 <Callout type="warn">
-`vi.mock()` and related calls do _not_ work inside workflow functions, only step functions. Your workflow functions cannot import third party code that needs to be mocked. Mocking works for npm packages imported in step functions. If something needs to be mocked, it likely belongs inside a step function either way.
+`vi.mock()` cannot reach code inside workflow functions at all, and reaches step code only under specific conditions. Read [Mocking](#mocking) before reaching for it.
+</Callout>
+
+### Installation
+
+```package-install
+npm i -D @workflow/vitest@beta
+```
+
+<Callout type="warn">
+**Workflow 5 needs the `beta` tag.** `@workflow/vitest@latest` is still the 4.x line, so a plain `npm i -D @workflow/vitest` installs a v4 plugin next to a v5 app. Install `@workflow/vitest@beta`, or pin the beta your app is on (for example `@workflow/vitest@5.0.0-beta.53`), and upgrade it together with `workflow`.
+
+The plugin builds and runs your workflows against the copy of `@workflow/core` it was installed with, so it checks this for you. At the start of each run it compares that copy with the one your app resolves: a different major fails the run with the install command that fixes it, and any other difference logs a warning. Set [`WORKFLOW_VITEST_VERSION_CHECK=off`](/docs/configuration/build-and-diagnostics#workflow_vitest_version_check) to skip the check.
 </Callout>
 
 ### Vitest configuration
@@ -303,6 +315,72 @@ describe("ingestWorkflow", () => {
 });
 ```
 
+### Referencing workflows by name
+
+Importing the workflow function is the best way to start it: [`start()`](/docs/api-reference/workflow-api/start) keeps its argument and return types. When a test cannot import it, because the workflow lives in a module the test does not pull in or because the test drives runs by name, look it up with [`getWorkflowRef()`](/docs/api-reference/vitest#getworkflowref) instead of hand-writing the generated `workflow//...` id:
+
+```typescript title="workflows/approval.integration.test.ts" lineNumbers
+import { describe, it, expect } from "vitest";
+import { start } from "workflow/api";
+import { getWorkflowRef, listWorkflowRefs } from "@workflow/vitest"; // [!code highlight]
+
+describe("approvalWorkflow", () => {
+  it("is part of the test build", () => {
+    expect(listWorkflowRefs().map((ref) => ref.name)).toContain( // [!code highlight]
+      "approvalWorkflow"
+    );
+  });
+
+  it("can be started by name", async () => {
+    const run = await start(getWorkflowRef("approvalWorkflow"), ["doc-1"]); // [!code highlight]
+    expect(run.runId).toMatch(/^wrun_/);
+  });
+});
+```
+
+The names come from the manifest the test build writes next to its bundles, so they follow your code when files move. When one exported name appears in several files, qualify it with the file, `getWorkflowRef("workflows/approval.ts#approvalWorkflow")`, which also matches by path suffix. An unknown or ambiguous name throws with the workflows the build does contain.
+
+<Callout type="info">
+A reference is matched by name, so the run is typed as `Run<unknown>`. Import the workflow function when you want the argument and return types checked.
+</Callout>
+
+### Mocking
+
+Steps do not run from your test file's module graph. They run from the bundles the plugin builds, and workflow bodies run from a code string inside the sandboxed VM, so `vi.mock()` reaches less here than in an ordinary Vitest test:
+
+| What you mock | Step code sees it | Workflow body sees it |
+| --- | --- | --- |
+| An npm package a step file imports | Only when the generated bundles load through Vitest's module runner (see below) | No |
+| An npm package imported by a local module that a step file imports | Same as above | No |
+| A project-local module a step file imports | No: it is bundled into the step bundle, so there is no module left to replace | No |
+| A step function imported and called directly, with no `workflow()` plugin | Yes, ordinary Vitest rules | n/a |
+
+Workflow bodies execute in a VM that has no module registry, so nothing can intercept their imports. That is the same reason side effects belong in steps: if a dependency needs mocking, it belongs on the step side.
+
+Whether step code sees an npm mock depends on how Vitest loaded the plugin. In a normal install `@workflow/vitest` is external to Vitest, Node loads the generated bundle directly, and steps get the real package. Ask for the other behavior explicitly:
+
+```typescript title="vitest.integration.config.ts" lineNumbers
+import { defineConfig } from "vitest/config";
+import { workflow } from "@workflow/vitest";
+
+export default defineConfig({
+  plugins: [workflow()],
+  test: {
+    // Route the generated bundles through Vitest's module runner, so vi.mock()
+    // applies to the npm packages your steps import.
+    server: { deps: { inline: [/@workflow\/vitest/] } }, // [!code highlight]
+  },
+});
+```
+
+The cost is that the generated bundle goes through Vite's transform pipeline in every test worker.
+
+Three approaches work regardless of how the plugin was loaded:
+
+- **Unit test the step directly.** Without the plugin, `"use step"` is a no-op and the function is an ordinary async function, so `vi.mock()` behaves normally.
+- **Pass the dependency in.** A step that takes its collaborator as an argument is controlled by the caller, with no module interception involved.
+- **Feed values through hooks.** Resume a [hook](/docs/foundations/hooks) with the data you want instead of mocking whatever would have produced it.
+
 ### Manual setup
 
 If you need more control over the test lifecycle, the plugin also exports the individual setup functions:
@@ -403,6 +481,10 @@ Workflows may take longer to execute than typical unit tests, especially when th
 
 Integration tests are the right place to verify that your workflows handle errors correctly, including retryable errors, fatal errors, and timeout scenarios.
 
+### Upgrade `@workflow/vitest` with the SDK
+
+`@workflow/vitest` carries its own copy of the Workflow runtime, so treat it as part of the same upgrade as `workflow`. While Workflow 5 is in beta, that means the `beta` tag on both. See [Installation](#installation).
+
 ## Further reading
 
 - [Hooks & Webhooks](/docs/foundations/hooks) - Pausing and resuming workflows with external data
@@ -410,7 +492,7 @@ Integration tests are the right place to verify that your workflows handle error
 - [`resumeHook()` API Reference](/docs/api-reference/workflow-api/resume-hook) - Resume hooks with data
 - [`resumeWebhook()` API Reference](/docs/api-reference/workflow-api/resume-webhook) - Resume webhooks with Request objects
 - [`getRun()` API Reference](/docs/api-reference/workflow-api/get-run) - Check workflow run status and wake up sleeping runs
-- [`@workflow/vitest` API Reference](/docs/api-reference/vitest) - Test helpers: `waitForSleep()`, `waitForHook()`, and plugin setup
+- [`@workflow/vitest` API Reference](/docs/api-reference/vitest) - Test helpers: `waitForSleep()`, `waitForHook()`, `getWorkflowRef()`, and plugin setup
 - [Vite Integration](/docs/getting-started/vite) - Set up the Vite plugin
 - [Observability](/docs/observability) - Inspect and debug workflow runs with the CLI and Web UI
 - [Server-based testing](/docs/testing/server-based) - Integration testing with a running server

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow",
-  "version": "5.0.0-beta.53",
+  "version": "5.0.0-beta.55",
   "description": "Workflow SDK - Build durable, resilient, and observable workflows",
   "main": "dist/typescript-plugin.cjs",
   "type": "module",
@@ -58,19 +58,19 @@
     }
   },
   "dependencies": {
-    "@workflow/astro": "5.0.0-beta.53",
-    "@workflow/cli": "5.0.0-beta.53",
-    "@workflow/core": "5.0.0-beta.53",
-    "@workflow/errors": "5.0.0-beta.21",
+    "@workflow/astro": "5.0.0-beta.55",
+    "@workflow/cli": "5.0.0-beta.55",
+    "@workflow/core": "5.0.0-beta.55",
+    "@workflow/errors": "5.0.0-beta.22",
     "@workflow/typescript-plugin": "5.0.0-beta.5",
     "@workflow/utils": "5.0.0-beta.10",
     "ms": "2.1.3",
-    "@workflow/next": "5.0.0-beta.53",
-    "@workflow/nest": "5.0.0-beta.53",
-    "@workflow/nitro": "5.0.0-beta.53",
-    "@workflow/nuxt": "5.0.0-beta.53",
-    "@workflow/sveltekit": "5.0.0-beta.53",
-    "@workflow/rollup": "5.0.0-beta.53"
+    "@workflow/next": "5.0.0-beta.55",
+    "@workflow/nest": "5.0.0-beta.55",
+    "@workflow/nitro": "5.0.0-beta.55",
+    "@workflow/nuxt": "5.0.0-beta.55",
+    "@workflow/sveltekit": "5.0.0-beta.55",
+    "@workflow/rollup": "5.0.0-beta.55"
   },
   "devDependencies": {
     "@types/ms": "2.1.0",