Make start() types unknown when deploymentId is provided

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

@@ -60,7 +60,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.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.
    *
@@ -28,21 +41,24 @@ export interface StartOptions {
    * @deprecated This property should not be set in user code under normal circumstances.
    * It is automatically inferred from environment variables when deploying to Vercel.
    * Only set this if you are doing something advanced and know what you are doing.
+   *
+   * **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.
  */
@@ -63,15 +79,28 @@ 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
+export function start(
+  workflow: WorkflowFunction<unknown[], unknown> | WorkflowMetadata,
+  args: unknown[],
+  options: StartOptionsWithDeploymentId
+): Promise<Run<unknown>>;
+
+export function start(
+  workflow: WorkflowFunction<unknown[], unknown> | 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>(