Make start() types unknown when deploymentId is provided (#1367)

* fix: update types and documentation for start function overloads

Ensure types are 'unknown[]' and 'unknown' for 'deploymentId' and update exports and documentation.

Slack-Thread: https://vercel.slack.com/archives/C09G3EQAL84/p1773368990070059?thread_ts=1773368990.070059&cid=C09G3EQAL84
Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com>

* fix: use generics in deploymentId overloads to avoid contravariance issue

Addresses PR review feedback: typed workflows like
WorkflowFunction<[string], number> were not assignable to
WorkflowFunction<unknown[], unknown> under strictFunctionTypes.
Changed to generic parameters while keeping Run<unknown> return type.
Also adds type-level tests for overload resolution.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore: add changeset for start() deploymentId type changes

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: v0 <v0[bot]@users.noreply.github.com>
Co-authored-by: Pranay Prakash <1797812+pranaygp@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 3 people

.changeset/start-deploymentid-unknown-types.md

@@ -0,0 +1,5 @@
+---
+"@workflow/core": patch
+---
+
+Make `start()` return `Run<unknown>` with `unknown[]` args when `deploymentId` is provided, since the deployed workflow version may have different types

docs/content/docs/api-reference/workflow-api/start.mdx

@@ -54,6 +54,7 @@ Learn more about [`WorkflowReadableStreamOptions`](/docs/api-reference/workflow-
 * This is different from calling workflow functions directly, which is the typical pattern in Next.js applications.
 * The function returns immediately after enqueuing the workflow - it doesn't wait for the workflow to complete.
 * All arguments must be [serializable](/docs/foundations/serialization).
+* When `deploymentId` is provided, the argument types and return type become `unknown` since there is no guarantee the workflow function's types will be consistent across different deployments.
 
 ## Examples
 

packages/core/src/runtime.ts

@@ -71,7 +71,13 @@ export {
   type StopSleepResult,
   wakeUpRun,
 } from './runtime/runs.js';
-export { type StartOptions, start } from './runtime/start.js';
+export {
+  type StartOptions,
+  type StartOptionsBase,
+  type StartOptionsWithDeploymentId,
+  type StartOptionsWithoutDeploymentId,
+  start,
+} from './runtime/start.js';
 export { stepEntrypoint } from './runtime/step-handler.js';
 export {
   createWorld,

packages/core/src/runtime/start.test.ts

@@ -1,7 +1,17 @@
 import { WorkflowRuntimeError } from '@workflow/errors';
 import { SPEC_VERSION_CURRENT, SPEC_VERSION_LEGACY } from '@workflow/world';
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  expectTypeOf,
+  it,
+  vi,
+} from 'vitest';
+import type { Run } from './run.js';
 import { start } from './start.js';
+import type { WorkflowFunction } from './start.js';
 import { getWorld } from './world.js';
 
 // Mock @vercel/functions
@@ -380,4 +390,47 @@ describe('start', () => {
       );
     });
   });
+
+  describe('overload type inference', () => {
+    // Type-only assertions that don't execute start() at runtime.
+    // We use expectTypeOf on the function signature's return type directly.
+
+    type TypedWf = WorkflowFunction<[string, number], boolean>;
+    type ZeroArgWf = WorkflowFunction<[], string>;
+    type Meta = { workflowId: string };
+
+    it('should preserve types without deploymentId', () => {
+      // With args
+      expectTypeOf<
+        (wf: TypedWf, args: [string, number]) => Promise<Run<boolean>>
+      >().toMatchTypeOf<typeof start>();
+
+      // Zero-arg workflow without args
+      expectTypeOf(start<string>)
+        .parameter(0)
+        .toMatchTypeOf<ZeroArgWf | Meta>();
+    });
+
+    it('should return Run<unknown> when deploymentId is provided', () => {
+      // Typed workflow with deploymentId - return type becomes Run<unknown>
+      type StartWithDeploymentId = (
+        wf: TypedWf | Meta,
+        args: unknown[],
+        opts: { deploymentId: string }
+      ) => Promise<Run<unknown>>;
+      expectTypeOf<StartWithDeploymentId>().toMatchTypeOf<typeof start>();
+    });
+
+    it('should accept typed workflows with deploymentId (no contravariance issue)', () => {
+      // This is the key test: a typed workflow should be assignable to the
+      // deploymentId overload. We verify by checking the first parameter
+      // accepts TypedWf.
+      type DeploymentIdOverload = <TArgs extends unknown[], TResult>(
+        wf: WorkflowFunction<TArgs, TResult> | Meta,
+        args: unknown[],
+        opts: { deploymentId: string }
+      ) => Promise<Run<unknown>>;
+      expectTypeOf<DeploymentIdOverload>().toMatchTypeOf<typeof start>();
+    });
+  });
 });

packages/core/src/runtime/start.ts

@@ -17,7 +17,20 @@ import { getWorld } from './world.js';
 /** ULID generator for client-side runId generation */
 const ulid = monotonicFactory();
 
-export interface StartOptions {
+export interface StartOptionsBase {
+  /**
+   * The world to use for the workflow run creation,
+   * by default the world is inferred from the environment variables.
+   */
+  world?: World;
+
+  /**
+   * The spec version to use for the workflow run. Defaults to the latest version.
+   */
+  specVersion?: number;
+}
+
+export interface StartOptionsWithDeploymentId extends StartOptionsBase {
   /**
    * The deployment ID to use for the workflow run.
    *
@@ -27,21 +40,24 @@ export interface StartOptions {
    * Set to `'latest'` to automatically resolve the most recent deployment
    * for the current environment (same production target or git branch).
    * This is currently a Vercel-specific feature.
+   *
+   * **Note:** When `deploymentId` is provided, the argument and return types become `unknown`
+   * since there is no guarantee the types will be consistent across deployments.
    */
-  deploymentId?: 'latest' | (string & {});
-
-  /**
-   * The world to use for the workflow run creation,
-   * by default the world is inferred from the environment variables.
-   */
-  world?: World;
+  deploymentId: 'latest' | (string & {});
+}
 
-  /**
-   * The spec version to use for the workflow run. Defaults to the latest version.
-   */
-  specVersion?: number;
+export interface StartOptionsWithoutDeploymentId extends StartOptionsBase {
+  deploymentId?: undefined;
 }
 
+/**
+ * Options for starting a workflow run.
+ */
+export type StartOptions =
+  | StartOptionsWithDeploymentId
+  | StartOptionsWithoutDeploymentId;
+
 /**
  * Represents an imported workflow function.
  */
@@ -62,15 +78,30 @@ export type WorkflowMetadata = { workflowId: string };
  * @param options - The options for the workflow run (optional).
  * @returns The unique run ID for the newly started workflow invocation.
  */
+// Overloads with deploymentId - args and return type become unknown
+// Uses generics so typed workflows are assignable (avoids contravariance issues),
+// but the return type and args are still unknown since the deployed version may differ.
+export function start<TArgs extends unknown[], TResult>(
+  workflow: WorkflowFunction<TArgs, TResult> | WorkflowMetadata,
+  args: unknown[],
+  options: StartOptionsWithDeploymentId
+): Promise<Run<unknown>>;
+
+export function start<TResult>(
+  workflow: WorkflowFunction<[], TResult> | WorkflowMetadata,
+  options: StartOptionsWithDeploymentId
+): Promise<Run<unknown>>;
+
+// Overloads without deploymentId - preserve type inference
 export function start<TArgs extends unknown[], TResult>(
   workflow: WorkflowFunction<TArgs, TResult> | WorkflowMetadata,
   args: TArgs,
-  options?: StartOptions
+  options?: StartOptionsWithoutDeploymentId
 ): Promise<Run<TResult>>;
 
 export function start<TResult>(
   workflow: WorkflowFunction<[], TResult> | WorkflowMetadata,
-  options?: StartOptions
+  options?: StartOptionsWithoutDeploymentId
 ): Promise<Run<TResult>>;
 
 export async function start<TArgs extends unknown[], TResult>(

packages/core/src/serialization.ts

@@ -570,8 +570,7 @@ export class WorkflowServerWritableStream extends WritableStream<Uint8Array> {
         // unsettled promise because the cleared timer will never fire.
         const waiters = flushWaiters;
         flushWaiters = [];
-        const abortError =
-          reason ?? new Error("Stream aborted");
+        const abortError = reason ?? new Error('Stream aborted');
         for (const w of waiters) w.reject(abortError);
       },
     });