@workflow/core 4.2.0-beta.76 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workflow/core",
-  "version": "4.2.0-beta.76",
+  "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.49",
-    "@workflow/world-vercel": "4.1.0-beta.47"
+    "@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",