@workflow/core 4.2.0-beta.75 → 4.2.0-beta.78

package/docs/how-it-works/framework-integrations.mdx

@@ -261,6 +261,35 @@ class MyFrameworkBuilder extends BaseBuilder {
 
 If your framework supports virtual server routes and dev mode watching, make sure to adapt accordingly. Please open a PR to the Workflow SDK if the base builder class is missing necessary functionality.
 
+### Monorepos and Workspace Imports
+
+If your framework integration lives in a subdirectory and your workflows import code from sibling workspace packages, pass `projectRoot` to `BaseBuilder`. Use the smallest directory that contains every workspace package imported by your workflows.
+
+{/* @skip-typecheck: @workflow/cli internal module */}
+```typescript title="my-framework-builder.ts" lineNumbers
+import { BaseBuilder } from "@workflow/cli/dist/lib/builders/base-builder";
+
+class MyFrameworkBuilder extends BaseBuilder {
+  constructor(options: {
+    rootDir: string;
+    workspaceRoot?: string;
+    dev: boolean;
+  }) {
+    super({
+      dirs: ["workflows"],
+      workingDir: options.rootDir,
+      projectRoot: options.workspaceRoot ?? options.rootDir, // [!code highlight]
+      watch: options.dev,
+    });
+  }
+
+  override async build(): Promise<void> {
+    const inputFiles = await this.getInputFiles();
+    // ...
+  }
+}
+```
+
 Hook into your framework's build:
 
 {/* @skip-typecheck: incomplete code sample */}
@@ -346,22 +375,50 @@ In the future, the Workflow SDK will emit more routes under the `.well-known/wor
 
 ## Security
 
-**How are these HTTP endpoints secured?**
+The workflow and step handler endpoints are invoked by the world's queuing infrastructure, not by end users. How they're secured depends on which world you're deploying to.
+
+### Vercel (`@workflow/world-vercel`)
+
+On Vercel, workflow handler functions are not accessible through public endpoints. Handlers use the same [consumer function security](https://vercel.com/docs/queues/concepts#consumer-function-security) mechanism that secures [Vercel Queues](https://vercel.com/docs/queues) consumers.
+
+During the build step, the Workflow SDK automatically configures each handler as a queue consumer by writing `experimentalTriggers` to the function's `.vc-config.json`:
+
+```json title=".vc-config.json (generated by Workflow SDK)"
+{
+  "experimentalTriggers": [
+    {
+      "type": "queue/v2beta",
+      "topic": "__wkf_step_*",
+      "consumer": "default",
+      "retryAfterSeconds": 5,
+      "initialDelaySeconds": 0
+    }
+  ]
+}
+```
+
+
+Two queue topics are created per deployment:
 
-Security is handled by the **world abstraction** you're using:
+| Handler | Topic | Description |
+| --- | --- | --- |
+| `step.func` | `__wkf_step_*` | Step execution (long-running, `maxDuration: max`) |
+| `flow.func` | `__wkf_workflow_*` | Workflow orchestration (`maxDuration: 60`) |
+
+If you're building a framework integration that targets Vercel, you should write these triggers into the `.vc-config.json` for each generated function. The `STEP_QUEUE_TRIGGER` and `WORKFLOW_QUEUE_TRIGGER` constants are exported from `@workflow/builders` for this purpose:
+
+```typescript
+import { STEP_QUEUE_TRIGGER, WORKFLOW_QUEUE_TRIGGER } from "@workflow/builders";
+```
 
-**Vercel (`@workflow/world-vercel`):**
 
-- Vercel Queue will support private invoke, making routes inaccessible from the public internet
-- Handlers receive only a message ID that must be retrieved from Vercel's backend
-- Impossible to craft custom payloads without valid queue-issued message IDs
+### Custom implementations
 
-**Custom implementations:**
+For self-hosted or non-Vercel deployments, you are responsible for securing the handler endpoints:
 
-- Implement authentication via framework middleware
-- Use API keys, JWT validation, or other auth schemes
-- Network-level security (VPCs, private networks, firewall rules)
-- Rate limiting and request validation
+- **Framework middleware** — Add authentication (API keys, JWT, OIDC) in front of the `/.well-known/workflow/v1/*` routes
+- **Network-level security** — Deploy handlers behind a VPC, private network, or firewall rules so only your queue infrastructure can reach them
+- **Rate limiting** — Add request validation and rate limiting to prevent abuse
 
 Learn more about [building custom Worlds](/docs/deploying/building-a-world).
 

package/docs/how-it-works/understanding-directives.mdx

@@ -15,7 +15,7 @@ import { File, Folder, Files } from "fumadocs-ui/components/files";
 This guide explores how JavaScript directives enable the Workflow SDK's execution model. For getting started with workflows, see the [getting started](/docs/getting-started) guides for your framework.
 </Callout>
 
-The Workflow Development Kit uses JavaScript directives (`"use workflow"` and `"use step"`) as the foundation for its durable execution model. Directives provide the compile-time semantic boundary necessary for workflows to suspend, resume, and maintain deterministic behavior across replays.
+The Workflow SDK uses JavaScript directives (`"use workflow"` and `"use step"`) as the foundation for its durable execution model. Directives provide the compile-time semantic boundary necessary for workflows to suspend, resume, and maintain deterministic behavior across replays.
 
 This page explores how directives enable this execution model and the design principles that led us here.
 
@@ -339,7 +339,7 @@ This approach requires:
 - Storing/mutating class properties was not obvious (similar closure/mutation issues as the runtime-only approach)
 - Class-based syntax that doesn't feel "JavaScript native" to developers used to functional patterns
 
-As the JavaScript ecosystem has moved toward function-forward programming (exemplified by React's shift from class components to functions and hooks), requiring developers to use classes felt like a step backward and also didn't match our own personal taste as authors of the DevKit.
+As the JavaScript ecosystem has moved toward function-forward programming (exemplified by React's shift from class components to functions and hooks), requiring developers to use classes felt like a step backward and also didn't match our own personal taste as authors of the SDK.
 
 **The core problem: Presents workflows as regular runtime code**
 
@@ -615,4 +615,4 @@ As TC39 members, we at Vercel are actively working with the standards body and b
 
 Directives aren't about syntax preference, they're about expressing semantic boundaries. `"use workflow"` tells the compiler, developer, and runtime that this code is deterministic, resumable, and sandboxed.
 
-This clarity enables the Workflow Development Kit to provide durable execution with familiar JavaScript patterns, while maintaining the compile-time guarantees necessary for reliable workflow orchestration.
+This clarity enables the Workflow SDK to provide durable execution with familiar JavaScript patterns, while maintaining the compile-time guarantees necessary for reliable workflow orchestration.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workflow/core",
-  "version": "4.2.0-beta.75",
+  "version": "4.2.0-beta.78",
   "description": "Core runtime and engine for Workflow SDK",
   "type": "module",
   "main": "dist/index.js",
@@ -83,9 +83,9 @@
     "@workflow/errors": "4.1.0-beta.20",
     "@workflow/serde": "4.1.0-beta.2",
     "@workflow/utils": "4.1.0-beta.13",
-    "@workflow/world": "4.1.0-beta.15",
-    "@workflow/world-local": "4.1.0-beta.48",
-    "@workflow/world-vercel": "4.1.0-beta.46"
+    "@workflow/world": "4.1.0-beta.17",
+    "@workflow/world-local": "4.1.0-beta.51",
+    "@workflow/world-vercel": "4.1.0-beta.49"
   },
   "devDependencies": {
     "@opentelemetry/api": "1.9.0",