workerflow 0.2.0 → 0.3.0

package/README.md

@@ -33,22 +33,14 @@ tag = "v1"
 new_sqlite_classes = ["OrderWorkflowRuntime"]
 ```
 
-In your Worker module, export the runtime, the definition, and a **`fetch`** handler (or queue consumer, cron trigger, and so on) that obtains a namespace stub and calls **`create`** to pin a definition version and optional input:
+In your Worker module, export the runtime, the definition, and a **`fetch`** handler (or queue consumer, cron trigger, and so on) that obtains a namespace stub and calls **`create`** to pin the workflow input:
 
 ```ts
 // src/worker.ts
 import { WorkflowDefinition, WorkflowRuntime } from "workerflow";
 
 export class OrderWorkflowRuntime extends WorkflowRuntime<{ orderId: string }> {
-  /** Resolves which `WorkerEntrypoint` implementation runs for a pinned `definitionVersion`. */
-  protected getDefinition(version: string) {
-    switch (version) {
-      case "2026-04-01":
-        return this.ctx.exports.OrderWorkflowDefinition;
-      default:
-        throw new Error(`Unsupported workflow definition version: ${version}`);
-    }
-  }
+  protected readonly definition = this.ctx.exports.OrderWorkflowDefinition;
 }
 
 export class OrderWorkflowDefinition extends WorkflowDefinition<{ orderId: string }> {
@@ -79,7 +71,7 @@ export default {
     if (url.pathname === "/orders") {
       const orderId = "new-order";
       const stub = env.ORDER_WORKFLOW.getByName(orderId);
-      await stub.create({ definitionVersion: "2026-04-01", input: { orderId } });
+      await stub.create({ orderId });
       return Response.json({ id: orderId });
     }
 
@@ -88,18 +80,18 @@ export default {
 } satisfies ExportedHandler<Env>;
 ```
 
-Workflow input is **`this.ctx.props.input`**, populated from **`create({ input })`**. The runtime also sets **`this.ctx.props.requestId`** (a new UUID each time the run loop invokes your definition) and **`this.ctx.props.runtimeInstanceId`** (this Durable Object’s id) for logs and correlation. Use a **stable `definitionVersion`** string per deploy you want long-running instances to keep using; add a new version in **`getDefinition`** when you ship breaking definition changes.
+Workflow input is **`this.ctx.props.input`**, populated from **`create(input)`**. TypeScript requires an input argument when your runtime's **`TInput`** excludes **`undefined`**; no-input workflows can use **`WorkflowRuntime<undefined>`**, and optionally-input workflows can include **`undefined`** in the input type. The runtime also sets **`this.ctx.props.requestId`** (a new UUID each time the run loop invokes your definition) and **`this.ctx.props.runtimeInstanceId`** (this Durable Object’s id) for logs and correlation.
 
 ### Runtime control
 
 From the Durable Object stub you can:
 
-- **`create({ definitionVersion, input? })`** — Pins the version and optional input in SQLite the **first** time the instance is initialized, then starts execution. **No-op** if the workflow is already **completed**, **failed**, **cancelled**, or **paused**. Throws if the object was already pinned to a **different** version.
+- **`create(input)`** — Pins the workflow input in SQLite the **first** time the instance is initialized, then starts execution. The input argument is required unless **`TInput`** includes **`undefined`**. **No-op** if the workflow is already **completed**, **failed**, **cancelled**, or **paused**.
 - **`pause()`** — When status is **running**, moves to **paused**, clears alarms, and stops driving **`execute()`** until **`resume()`**. Inbound events are queued and applied when a matching **`wait`** runs again after resume.
 - **`resume()`** — When status is **paused**, moves to **running** and continues the loop. Throws if the workflow is not paused.
 - **`cancel(reason?)`** — Moves to terminal **cancelled** and clears alarms.
 
-New instances start in **`pending`** until the first transition to **`running`**.
+New instances start in **`pending`**. The first **`create()`** call moves the instance through the durable **`initialized`** state before execution enters **`running`**.
 
 ### Experimental introspection
 
@@ -193,27 +185,21 @@ At this point there is no sleep alarm, no retry alarm, and no wait-timeout alarm
 
 There is also a guard for the case where an alarm fires while the run loop is already active — for example, a sleep's precise alarm arriving while the loop is processing another step in the same Durable Object invocation. In that situation the alarm handler simply reschedules the watchdog for another 30 minutes rather than starting a second concurrent loop, keeping the safety net in place until the active loop finishes.
 
-### Versioning
-
-`create({ definitionVersion, input })` **pins** the definition version and optional input in SQLite the first time the instance is initialized (see [Runtime control](#runtime-control) for no-op cases). **The version cannot be changed later** for that Durable Object id; attempting a different version throws. Every subsequent `next()` resolves the worker implementation via **`getDefinition(version)`** using that pinned value, so **long-lived workflows keep running the definition lineage they started with**, while new instances can use newer version strings you add to `getDefinition`.
-
 ## Why this exists
 
-Cloudflare Workflows is a strong managed option, and for many use cases it is the right tradeoff. I built `workerflow` for cases where I wanted tighter control over runtime behavior, definition versioning, and state projection than the managed model naturally gives me.
+Cloudflare Workflows is a strong managed option, and for many use cases it is the right tradeoff. I built `workerflow` for cases where I wanted tighter control over runtime behavior, replay semantics, and state projection than the managed model naturally gives me.
 
 1. Explicit ownership of workflow state and lifecycle
-2. A clear story for versioning workflow definitions
+2. Durable replay semantics that are explicit in userland code
 3. Separation between workflow execution and external state synchronization
 4. Extension points for streaming, WebSockets, and custom hooks
 5. Fewer surprises around long-lived execution and error handling
 
-### Versioning workflow definitions
+### Definition compatibility
 
 One of the biggest concerns in long-running workflows is definition drift. A normal Worker request is typically bound to a single in-flight execution on one deployed version, but a Workflow is durable: it persists state and resumes across multiple executions over time. A workflow may start on one version of its definition and resume later after a deploy has changed or removed a step. That means the next invocation of the workflow entry point could repeat steps unsafely or leave the runtime in an invalid state.
 
-Versioning does not eliminate these problems, but it makes the risk explicit. It forces you to think about compatibility, migration, and long-lived execution up front. Cloudflare Workflows can support version-aware workflows by passing a version token in the immutable per-instance parameters and branching in workflow code or by maintaining a version mapping in an external database, but both are conventions that your application is responsible for maintaining.
-
-`workerflow` takes a different approach: the runtime pins a definition version when the instance is created and resolves future execution against that pinned version. The goal is not to make compatibility problems disappear, but to make the version boundary explicit in the runtime rather than implicit in workflow input and application code.
+`workerflow` keeps definition selection simple: each runtime points at one definition entrypoint, and the input is the only per-instance payload pinned by `create(input)`. If a workflow needs version-aware behavior, model that explicitly in your input shape and keep old branches compatible until the long-lived instances that need them have completed.
 
 ### Keeping workflow execution separate from state projection
 
@@ -245,11 +231,9 @@ I think a cleaner design is to keep synchronization logic out of workflow steps
 
 ```ts
 export class MyWorkflowRuntime extends WorkflowRuntime {
-  async onStatusChange_experimental(
-    status: "running" | "paused" | "completed" | "failed" | "cancelled"
-  ) {
+  async onStatusChange_experimental(status: "running" | "paused" | "completed" | "failed" | "cancelled") {
     // Update your database, or push to a queue for streaming.
-    // Note: the hook is also invoked with "running" when leaving pending/paused into running.
+    // Note: the hook is also invoked with "running" when leaving initialized/paused into running.
   }
 }
 ```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "workerflow",
   "description": "Durable execution engine, built on Cloudflare Workers",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "exports": {
     ".": {

package/src/json.ts

@@ -1,12 +1,10 @@
 /**
- * Represents an indefinitely deep arbitrary JSON data structure. There are
- * four types that make up the Json family:
- *
- * - Json         any legal JSON value
- * - JsonScalar   any legal JSON leaf value (no lists or objects)
- * - JsonArray    a JSON value whose outer type is an array
- * - JsonObject   a JSON value whose outer type is an object
+ * Represents an indefinitely deep arbitrary JSON data structure. There are four types that make up the Json family:
  *
+ * - Json any legal JSON value
+ * - JsonScalar any legal JSON leaf value (no lists or objects)
+ * - JsonArray a JSON value whose outer type is an array
+ * - JsonObject a JSON value whose outer type is an object
  */
 export type Json = JsonScalar | JsonArray | JsonObject;
 export type JsonScalar = string | number | boolean | null;

package/src/migrations/0000_initial.ts

@@ -5,7 +5,7 @@ export default `
     id INTEGER NOT NULL PRIMARY KEY CHECK (id = 1),
 
     status TEXT NOT NULL CHECK (
-      status IN ('pending', 'running', 'paused', 'completed', 'failed', 'cancelled')
+      status IN ('pending', 'initialized', 'running', 'paused', 'completed', 'failed', 'cancelled')
     ),
 
     created_at INTEGER NOT NULL
@@ -15,18 +15,13 @@ export default `
     updated_at INTEGER NOT NULL
       DEFAULT (CAST(unixepoch('subsecond') * 1000 AS INTEGER)),
 
-    definition_version TEXT
-      CHECK (definition_version IS NULL OR length(definition_version) > 0),
     definition_input TEXT
       CHECK (definition_input IS NULL OR json_valid(definition_input)),
 
     CHECK (updated_at >= created_at),
 
-    -- definition_input must be NULL if definition_version is NULL
-    CHECK (definition_version IS NOT NULL OR definition_input IS NULL),
-
-    -- definition must be pinned before running/paused/completing/failing; cancelled is always allowed
-    CHECK (status IN ('pending', 'cancelled') OR definition_version IS NOT NULL)
+    -- definition_input must be NULL until create() initializes the workflow.
+    CHECK (status <> 'pending' OR definition_input IS NULL)
   ) STRICT;
 
   CREATE TABLE steps (
@@ -278,8 +273,10 @@ export default `
   WHEN NEW.status <> OLD.status
   BEGIN
     SELECT CASE
-      WHEN OLD.status = 'pending' AND NEW.status NOT IN ('running', 'cancelled') THEN
-        RAISE(ABORT, 'pending can only transition to running or cancelled')
+      WHEN OLD.status = 'pending' AND NEW.status NOT IN ('initialized', 'cancelled') THEN
+        RAISE(ABORT, 'pending can only transition to initialized or cancelled')
+      WHEN OLD.status = 'initialized' AND NEW.status NOT IN ('running', 'cancelled') THEN
+        RAISE(ABORT, 'initialized can only transition to running or cancelled')
       WHEN OLD.status = 'running' AND NEW.status NOT IN ('paused', 'completed', 'failed', 'cancelled') THEN
         RAISE(ABORT, 'running can only transition to paused, completed, failed, or cancelled')
       WHEN OLD.status = 'paused' AND NEW.status NOT IN ('running', 'cancelled') THEN
@@ -289,6 +286,14 @@ export default `
     END;
   END;
 
+  CREATE TRIGGER workflow_metadata_definition_input_immutable_after_init
+  BEFORE UPDATE ON workflow_metadata
+  FOR EACH ROW
+  WHEN OLD.status <> 'pending' AND NEW.definition_input IS NOT OLD.definition_input
+  BEGIN
+    SELECT RAISE(ABORT, 'workflow_metadata.definition_input is immutable after initialization');
+  END;
+
   CREATE TRIGGER steps_immutable_identity_fields
   BEFORE UPDATE ON steps
   FOR EACH ROW

package/src/runtime.ts

@@ -4,15 +4,11 @@ import type { Json } from "./json";
 import mig000 from "./migrations/0000_initial";
 import type { Brand } from "./brand";
 
-export abstract class WorkflowRuntime<
-  TInput extends Json | undefined = Json | undefined,
-  TVersion extends string = string
-> extends DurableObject {
+export abstract class WorkflowRuntime<TInput extends Json | undefined = Json | undefined> extends DurableObject {
   private static readonly MIGRATIONS = [mig000];
   private readonly sql: SqlStorage;
   #status: WorkflowStatus;
   #isRunLoopActive: boolean = false;
-  #definitionVersion: TVersion | undefined;
   #definitionInput: TInput | undefined;
 
   /**
@@ -46,24 +42,19 @@ export abstract class WorkflowRuntime<
       console.error("Database migration version is ahead of the codebase. Please check your migrations.");
     }
 
-    const [metadata] = this.sql
-      .exec<WorkflowMetadata_Row<TVersion>>("SELECT * FROM workflow_metadata WHERE id = 1")
-      .toArray();
+    const [metadata] = this.sql.exec<WorkflowMetadata_Row>("SELECT * FROM workflow_metadata WHERE id = 1").toArray();
     if (metadata === undefined) {
       this.sql.exec("INSERT INTO workflow_metadata (id, status) VALUES (1, ?)", "pending");
       this.sql.exec("INSERT INTO workflow_events (type) VALUES (?)", "created");
       this.#status = "pending";
     } else {
       this.#status = metadata.status;
-      this.#definitionVersion = metadata.definition_version === null ? undefined : metadata.definition_version;
       this.#definitionInput =
         metadata.definition_input === null ? undefined : (JSON.parse(metadata.definition_input) as TInput);
     }
   }
 
-  protected abstract getDefinition(
-    version: TVersion
-  ): (options: {
+  protected abstract readonly definition: (options: {
     props: { requestId: string; runtimeInstanceId: string; input: TInput };
   }) => Fetcher<WorkflowDefinition<TInput>>;
 
@@ -321,49 +312,42 @@ export abstract class WorkflowRuntime<
   }
 
   /**
-   * Creates a new workflow instance and pins the definition version. If the workflow is in a terminal state, it will
-   * return early. Otherwise, it will pin the definition version and set the input. If the definition version is already
-   * pinned to a different version, it will throw an error.
+   * Creates a new workflow instance and pins the input. If the workflow is in a terminal state or paused, it will
+   * return early. Otherwise, it will pin the input the first time the instance is initialized and start execution.
    *
-   * @param options.definitionVersion - The version of the definition to pin to the workflow instance. This will be used
-   *   to resolve the workflow definition from the `getDefinition` hook.
-   * @param options.input - The input to the workflow instance. This will be passed to the workflow definition as the
-   *   `input` property.
+   * @param input - The input to the workflow instance. This will be passed to the workflow definition as the `input`
+   *   property.
    */
-  public async create(options: { definitionVersion: TVersion; input?: TInput }): Promise<void> {
+  public async create(...args: undefined extends TInput ? [input?: TInput] : [input: TInput]): Promise<void> {
+    const input = args[0];
     if (this.isTerminalStatus(this.#status)) return;
     if (this.#status === "paused") return;
 
-    const version = options.definitionVersion;
     let metadata = this.sql
-      .exec<Pick<WorkflowMetadata_Row<TVersion>, "definition_version" | "definition_input">>(
-        "SELECT definition_version, definition_input FROM workflow_metadata WHERE id = 1"
+      .exec<Pick<WorkflowMetadata_Row, "status" | "definition_input">>(
+        "SELECT status, definition_input FROM workflow_metadata WHERE id = 1"
       )
       .one();
 
-    if (metadata.definition_version !== null && metadata.definition_version !== version) {
-      throw new Error(
-        `Workflow definition version is already pinned to '${metadata.definition_version}' and cannot be changed to '${version}'.`
-      );
-    }
-
-    // If the workflow is not yet pinned to a definition version, we pin it to the new version and set the input.
-    if (metadata.definition_version === null) {
+    // If the workflow is not yet initialized, pin the input. `undefined` is encoded as SQL NULL.
+    if (metadata.status === "pending") {
       metadata = this.sql
-        .exec<Pick<WorkflowMetadata_Row<TVersion>, "definition_version" | "definition_input">>(
+        .exec<Pick<WorkflowMetadata_Row, "status" | "definition_input">>(
           `UPDATE workflow_metadata
-						SET definition_version = ?,
+						SET status = 'initialized',
 								definition_input = ?,
 								updated_at = CAST(unixepoch('subsecond') * 1000 AS INTEGER)
-						WHERE id = 1 RETURNING definition_version, definition_input`,
-          version,
-          options.input ? JSON.stringify(options.input) : null
+						WHERE id = 1
+							AND status = 'pending'
+						RETURNING status, definition_input`,
+          input === undefined ? null : JSON.stringify(input)
         )
         .one();
     }
 
-    this.#definitionVersion = version;
-    this.#definitionInput = metadata.definition_input ? (JSON.parse(metadata.definition_input) as TInput) : undefined;
+    this.#status = metadata.status;
+    this.#definitionInput =
+      metadata.definition_input === null ? undefined : (JSON.parse(metadata.definition_input) as TInput);
 
     await this.run();
   }
@@ -372,7 +356,7 @@ export abstract class WorkflowRuntime<
     if (this.isTerminalStatus(this.#status)) return;
     if (this.#status === "paused") return;
 
-    if (this.#definitionVersion === undefined) return;
+    if (this.#status === "pending") return;
 
     if (this.#status !== "running") {
       this.#setStatus({ type: "running" });
@@ -411,15 +395,11 @@ export abstract class WorkflowRuntime<
           }
 
           try {
-            const version = this.#definitionVersion;
-            if (version === undefined) {
-              throw new Error(
-                "Workflow definition version has not been initialized. Call 'create()' before running the workflow."
-              );
+            if (this.#status === "pending") {
+              throw new Error("Workflow input has not been initialized. Call 'create()' before running the workflow.");
             }
 
-            const definition = this.getDefinition(version);
-            const executor = definition({
+            const executor = this.definition({
               props: {
                 runtimeInstanceId: this.ctx.id.toString(),
                 requestId,
@@ -887,10 +867,7 @@ export type RunStepAttempt = {
   startedAt: Date;
 } & (
   | { state: "started" }
-  | ({ state: "succeeded"; endedAt: Date } & (
-      | { resultType: "json"; resultJson: string }
-      | { resultType: "none" }
-    ))
+  | ({ state: "succeeded"; endedAt: Date } & ({ resultType: "json"; resultJson: string } | { resultType: "none" }))
   | { state: "failed"; errorMessage: string; errorName?: string; endedAt: Date; nextAttemptAt?: Date }
 );
 
@@ -1294,18 +1271,18 @@ type TimedOutWaitStep_Row = Extract<WaitStep_Row, { state: "timed_out" }>;
 type Step_Row = RunStep_Row | SleepStep_Row | WaitStep_Row;
 
 export type WorkflowStatus =
-  | "pending" // The workflow has been created but 'run' hasn't been called yet
+  | "pending" // Durable metadata exists, but create() has not initialized the workflow input yet
+  | "initialized" // create() has pinned the workflow input, but execution has not started yet
   | "running" // The workflow is currently executing; steps are being created/processed
   | "paused" // The workflow is paused and will not make progress until resumed
   | "completed" // The workflow completed successfully; ('Workflow.next' returned { done: true, status: "succeeded" })
   | "failed" // A step exhausted retries and the workflow aborted; ('Workflow.next' returned { done: true, status: "failed" })
   | "cancelled"; // The workflow was terminated explicitly by the user.
 
-type WorkflowMetadata_Row<TVersion extends string> = {
+type WorkflowMetadata_Row = {
   created_at: number;
   updated_at: number;
   status: WorkflowStatus;
-  definition_version: TVersion | null;
   definition_input: string | null;
 };
 

package/test/runtime.spec.ts

@@ -48,7 +48,7 @@ describe("WorkflowRuntime", () => {
           resolve(status);
         };
 
-        await instance.create({ definitionVersion: "2026-03-19" });
+        await instance.create();
         await expect(promise).resolves.toBe("failed");
       });
     } finally {
@@ -71,7 +71,7 @@ describe("WorkflowRuntime", () => {
           if (status === "running") return;
           resolve(status);
         };
-        await instance.create({ definitionVersion: "2026-03-19" });
+        await instance.create();
         await expect(promise).resolves.toBe("failed");
       });
     } finally {
@@ -96,7 +96,7 @@ describe("WorkflowRuntime", () => {
           resolve(status);
         };
 
-        await instance.create({ definitionVersion: "2026-03-19" });
+        await instance.create();
         await expect(promise).resolves.toBe("failed");
         const steps = instance.getSteps_experimental();
         expect(steps).toHaveLength(1);
@@ -136,7 +136,7 @@ describe("WorkflowRuntime", () => {
           resolve(status);
         };
 
-        await instance.create({ definitionVersion: "2026-03-19" });
+        await instance.create();
         await expect(promise).resolves.toBe("failed");
         const steps = instance.getSteps_experimental();
         expect(steps).toHaveLength(1);
@@ -170,7 +170,7 @@ describe("WorkflowRuntime", () => {
           resolve(status);
         };
 
-        await instance.create({ definitionVersion: "2026-03-19" });
+        await instance.create();
         await expect(promise).resolves.toBe("failed");
       });
     } finally {
@@ -200,7 +200,7 @@ describe("WorkflowRuntime", () => {
           if (status === "running") return;
           resolve(status);
         };
-        await instance.create({ definitionVersion: "2026-03-19" });
+        await instance.create();
         await expect(promise).resolves.toBe("completed");
         const steps = instance.getSteps_experimental();
         expect(steps).toHaveLength(1);
@@ -237,7 +237,7 @@ describe("WorkflowRuntime", () => {
           resolve(status);
         };
 
-        await instance.create({ definitionVersion: "2026-03-19" });
+        await instance.create();
         await expect(promise).resolves.toBe("failed");
         const steps = instance.getSteps_experimental();
         expect(steps).toHaveLength(1);
@@ -268,7 +268,7 @@ describe("WorkflowRuntime", () => {
           resolve(status);
         };
 
-        await instance.create({ definitionVersion: "2026-03-19" });
+        await instance.create();
         await expect(promise).resolves.toBe("completed");
 
         const steps = instance.getSteps_experimental();
@@ -311,7 +311,7 @@ describe("WorkflowRuntime", () => {
           resolve(status);
         };
 
-        await instance.create({ definitionVersion: "2026-03-19" });
+        await instance.create();
         await expect(promise).resolves.toBe("completed");
 
         const steps = instance.getSteps_experimental();
@@ -351,7 +351,7 @@ describe("WorkflowRuntime", () => {
             if (status === "running") return;
             resolve(status);
           };
-          await instance.create({ definitionVersion: "2026-03-19", input });
+          await instance.create(input);
           await expect(promise).resolves.toBe("completed");
         });
         expect(received.length).toBeGreaterThanOrEqual(1);
@@ -363,27 +363,80 @@ describe("WorkflowRuntime", () => {
       }
     });
 
-    it("throws when the workflow is not terminal and definition version is already pinned to a different version", async () => {
+    it("does not repin input after the workflow is initialized", async () => {
+      const received: unknown[] = [];
       const executeSpy = vi
         .spyOn(TestWorkflowDefinition.prototype, "execute")
         .mockImplementation(async function (this: TestWorkflowDefinition) {
-          await this.wait("wait-1", "event-never", {
+          received.push(this.ctx.props.input);
+          await this.wait("wait-1", "event-done", {
             timeoutAt: Date.now() + 86_400_000
           });
         });
       try {
         const stub = env.TEST_WORKFLOW_RUNTIME.getByName(crypto.randomUUID());
         await runInDurableObject(stub, async (instance) => {
-          const { resolve, promise } = Promise.withResolvers<WorkflowStatus>();
+          const { resolve: resolveRunning, promise: running } = Promise.withResolvers<WorkflowStatus>();
+          const { resolve: resolveDone, promise: done } = Promise.withResolvers<WorkflowStatus>();
           instance.onStatusChange_experimental = async (status) => {
-            resolve(status);
+            if (status === "running") {
+              resolveRunning(status);
+            } else {
+              resolveDone(status);
+            }
           };
-          await instance.create({ definitionVersion: "2026-03-19" });
-          await expect(promise).resolves.toBe("running");
+          const input = { key: "original" };
+          await instance.create(input);
+          await expect(running).resolves.toBe("running");
 
-          await expect(instance.create({ definitionVersion: "2026-03-20" })).rejects.toThrow(
-            "Workflow definition version is already pinned to '2026-03-19' and cannot be changed to '2026-03-20'."
-          );
+          await instance.create({ key: "ignored" });
+          await instance.handleInboundEvent("event-done");
+          await expect(done).resolves.toBe("completed");
+
+          expect(received.length).toBeGreaterThanOrEqual(1);
+          for (const row of received) {
+            expect(row).toEqual(input);
+          }
+        });
+      } finally {
+        executeSpy.mockRestore();
+      }
+    });
+
+    it("does not repin undefined input after the workflow is initialized", async () => {
+      const received: unknown[] = [];
+      const executeSpy = vi
+        .spyOn(TestWorkflowDefinition.prototype, "execute")
+        .mockImplementation(async function (this: TestWorkflowDefinition) {
+          received.push(this.ctx.props.input);
+          await this.wait("wait-1", "event-done", {
+            timeoutAt: Date.now() + 86_400_000
+          });
+        });
+      try {
+        const stub = env.TEST_WORKFLOW_RUNTIME.getByName(crypto.randomUUID());
+        await runInDurableObject(stub, async (instance) => {
+          const { resolve: resolveRunning, promise: running } = Promise.withResolvers<WorkflowStatus>();
+          const { resolve: resolveDone, promise: done } = Promise.withResolvers<WorkflowStatus>();
+          instance.onStatusChange_experimental = async (status) => {
+            if (status === "running") {
+              resolveRunning(status);
+            } else {
+              resolveDone(status);
+            }
+          };
+
+          await instance.create();
+          await expect(running).resolves.toBe("running");
+
+          await instance.create({ key: "ignored" });
+          await instance.handleInboundEvent("event-done");
+          await expect(done).resolves.toBe("completed");
+
+          expect(received.length).toBeGreaterThanOrEqual(1);
+          for (const row of received) {
+            expect(row).toBeUndefined();
+          }
         });
       } finally {
         executeSpy.mockRestore();
@@ -398,11 +451,11 @@ describe("WorkflowRuntime", () => {
           if (status === "running") return;
           resolve(status);
         };
-        await instance.create({ definitionVersion: "2026-03-19" });
+        await instance.create();
         await expect(promise).resolves.toBe("completed");
         expect(instance.getStatus()).toBe("completed");
 
-        await instance.create({ definitionVersion: "2026-03-20" });
+        await instance.create();
         expect(instance.getStatus()).toBe("completed");
       });
     });
@@ -428,7 +481,7 @@ describe("WorkflowRuntime", () => {
             resolve(status);
           };
 
-          await instance.create({ definitionVersion: "2026-03-19" });
+          await instance.create();
           await expect(promise).resolves.toBe("completed");
 
           const steps = instance.getSteps_experimental();
@@ -466,7 +519,7 @@ describe("WorkflowRuntime", () => {
             resolve(status);
           };
 
-          await instance.create({ definitionVersion: "2026-03-19" });
+          await instance.create();
           await expect(promise).resolves.toBe("completed");
 
           const steps = instance.getSteps_experimental();
@@ -508,7 +561,7 @@ describe("WorkflowRuntime", () => {
             resolve(status);
           };
 
-          await instance.create({ definitionVersion: "2026-03-19" });
+          await instance.create();
           await expect(promise).resolves.toBe("completed");
 
           const steps = instance.getSteps_experimental();
@@ -549,7 +602,7 @@ describe("WorkflowRuntime", () => {
             resolve(status);
           };
 
-          await instance.create({ definitionVersion: "2026-03-19" });
+          await instance.create();
           await expect(promise).resolves.toBe("completed");
 
           const steps = instance.getSteps_experimental();
@@ -585,7 +638,7 @@ describe("WorkflowRuntime", () => {
             resolve(status);
           };
 
-          await instance.create({ definitionVersion: "2026-03-19" });
+          await instance.create();
           await expect(promise).resolves.toBe("completed");
 
           const steps = instance.getSteps_experimental();
@@ -619,7 +672,7 @@ describe("WorkflowRuntime", () => {
             resolve(status);
           };
 
-          await instance.create({ definitionVersion: "2026-03-19" });
+          await instance.create();
 
           await expect
             .poll(() => {
@@ -673,7 +726,7 @@ describe("WorkflowRuntime", () => {
             resolve(status);
           };
 
-          await instance.create({ definitionVersion: "2026-03-19" });
+          await instance.create();
           await expect(promise).resolves.toBe("failed");
 
           const steps = instance.getSteps_experimental();
@@ -720,7 +773,7 @@ describe("WorkflowRuntime", () => {
               resolve(status);
             };
 
-            await instance.create({ definitionVersion: "2026-03-19" });
+            await instance.create();
             await expect(promise).resolves.toBe("completed");
 
             expect(innerAttempts).toBe(2);
@@ -762,7 +815,7 @@ describe("WorkflowRuntime", () => {
               resolve(status);
             };
 
-            await instance.create({ definitionVersion: "2026-03-19" });
+            await instance.create();
             await expect(promise).resolves.toBe("failed");
 
             const steps = instance.getSteps_experimental();
@@ -805,7 +858,7 @@ describe("WorkflowRuntime", () => {
               resolve(status);
             };
 
-            await instance.create({ definitionVersion: "2026-03-19" });
+            await instance.create();
             await expect(promise).resolves.toBe("failed");
 
             const steps = instance.getSteps_experimental();
@@ -845,7 +898,7 @@ describe("WorkflowRuntime", () => {
               resolve(status);
             };
 
-            await instance.create({ definitionVersion: "2026-03-19" });
+            await instance.create();
             await expect
               .poll(() => {
                 const step = instance.getSteps_experimental().find((s) => s.id === "root-deep-wait");
@@ -895,7 +948,7 @@ describe("WorkflowRuntime", () => {
             resolve(status);
           };
 
-          await instance.create({ definitionVersion: "2026-03-19" });
+          await instance.create();
           await expect(promise).resolves.toBe("completed");
 
           const steps = instance.getSteps_experimental();
@@ -934,7 +987,7 @@ describe("WorkflowRuntime", () => {
             resolve(status);
           };
 
-          await instance.create({ definitionVersion: "2026-03-19" });
+          await instance.create();
           await expect(promise).resolves.toBe("completed");
 
           const steps = instance.getSteps_experimental();
@@ -978,7 +1031,7 @@ describe("WorkflowRuntime", () => {
             terminalStatuses.push(status);
           };
 
-          await instance.create({ definitionVersion: "2026-03-19" });
+          await instance.create();
           await expect.poll(() => instance.getStatus()).toBe("running");
           expect(terminalStatuses).toHaveLength(0);
 
@@ -1028,7 +1081,7 @@ describe("WorkflowRuntime", () => {
             terminalStatuses.push(status);
           };
 
-          await instance.create({ definitionVersion: "2026-03-19" });
+          await instance.create();
           await expect.poll(() => instance.getStatus()).toBe("running");
           expect(terminalStatuses).toHaveLength(0);
 
@@ -1065,7 +1118,7 @@ describe("WorkflowRuntime", () => {
           if (status === "running") return;
           resolve(status);
         };
-        await instance.create({ definitionVersion: "2026-03-19" });
+        await instance.create();
         await expect(promise).resolves.toBe("completed");
       });
 
@@ -1084,7 +1137,7 @@ describe("WorkflowRuntime", () => {
             if (status === "running") return;
             resolve(status);
           };
-          await instance.create({ definitionVersion: "2026-03-19" });
+          await instance.create();
           await expect(promise).resolves.toBe("failed");
         });
 
@@ -1117,7 +1170,7 @@ describe("WorkflowRuntime", () => {
       try {
         const stub = env.TEST_WORKFLOW_RUNTIME.getByName(crypto.randomUUID());
         await runInDurableObject(stub, async (instance) => {
-          await instance.create({ definitionVersion: "2026-03-19" });
+          await instance.create();
           await expect.poll(() => instance.getStatus()).toBe("running");
           await expect
             .poll(() => {
@@ -1151,7 +1204,7 @@ describe("WorkflowRuntime", () => {
             if (status === "paused") resolve();
           };
 
-          await instance.create({ definitionVersion: "2026-03-19" });
+          await instance.create();
           await instance.pause();
           await promise;
         });
@@ -1179,7 +1232,7 @@ describe("WorkflowRuntime", () => {
       try {
         const stub = env.TEST_WORKFLOW_RUNTIME.getByName(crypto.randomUUID());
         await runInDurableObject(stub, async (instance) => {
-          await instance.create({ definitionVersion: "2026-03-19" });
+          await instance.create();
           await expect.poll(() => instance.getStatus()).toBe("running");
           await instance.pause();
           expect(instance.getStatus()).toBe("paused");
@@ -1208,7 +1261,7 @@ describe("WorkflowRuntime", () => {
             resolve(status);
           };
 
-          await instance.create({ definitionVersion: "2026-03-19" });
+          await instance.create();
           await expect.poll(() => instance.getStatus()).toBe("running");
           await instance.pause();
           expect(instance.getStatus()).toBe("paused");
@@ -1241,7 +1294,7 @@ describe("WorkflowRuntime", () => {
       try {
         const stub = env.TEST_WORKFLOW_RUNTIME.getByName(crypto.randomUUID());
         await runInDurableObject(stub, async (instance) => {
-          await instance.create({ definitionVersion: "2026-03-19" });
+          await instance.create();
           await expect.poll(() => instance.getStatus()).toBe("running");
           await expect(instance.resume()).rejects.toThrow(
             "Cannot resume workflow: expected status 'paused' but got 'running'."
@@ -1262,7 +1315,7 @@ describe("WorkflowRuntime", () => {
       try {
         const stub = env.TEST_WORKFLOW_RUNTIME.getByName(crypto.randomUUID());
         await runInDurableObject(stub, async (instance) => {
-          await instance.create({ definitionVersion: "2026-03-19" });
+          await instance.create();
 
           await expect
             .poll(() => {
@@ -1306,7 +1359,7 @@ describe("WorkflowRuntime", () => {
             resolve(status);
           };
 
-          await instance.create({ definitionVersion: "2026-03-19" });
+          await instance.create();
           await expect
             .poll(() => {
               const step = instance.getSteps_experimental().find((s) => s.id === "wait-1");
@@ -1343,7 +1396,7 @@ describe("WorkflowRuntime", () => {
       try {
         const stub = env.TEST_WORKFLOW_RUNTIME.getByName(crypto.randomUUID());
         await runInDurableObject(stub, async (instance) => {
-          await instance.create({ definitionVersion: "2026-03-19" });
+          await instance.create();
           await expect.poll(() => instance.getStatus()).toBe("running");
           await expect
             .poll(() => {
@@ -1386,7 +1439,7 @@ describe("WorkflowRuntime", () => {
             resolve(status);
           };
 
-          await instance.create({ definitionVersion: "2026-03-19" });
+          await instance.create();
 
           await expect
             .poll(() => {
@@ -1437,7 +1490,7 @@ describe("WorkflowRuntime", () => {
             resolve(status);
           };
 
-          await instance.create({ definitionVersion: "2026-03-19" });
+          await instance.create();
 
           await expect
             .poll(() => {
@@ -1485,7 +1538,7 @@ describe("WorkflowRuntime", () => {
             resolve(status);
           };
 
-          await instance.create({ definitionVersion: "2026-03-19" });
+          await instance.create();
 
           await expect
             .poll(() => {
@@ -1533,7 +1586,7 @@ describe("WorkflowRuntime", () => {
             resolve(status);
           };
 
-          await instance.create({ definitionVersion: "2026-03-19" });
+          await instance.create();
 
           await expect
             .poll(() => {
@@ -1583,7 +1636,7 @@ describe("WorkflowRuntime", () => {
             resolve(status);
           };
 
-          await instance.create({ definitionVersion: "2026-03-19" });
+          await instance.create();
           await expect(promise).resolves.toBe("completed");
 
           // Should not throw even though there is no matching wait step
@@ -1609,7 +1662,7 @@ describe("WorkflowRuntime", () => {
       });
     });
 
-    it("records 'started' when workflow transitions from pending to running", async () => {
+    it("records 'started' when workflow transitions from initialized to running", async () => {
       const executeSpy = vi
         .spyOn(TestWorkflowDefinition.prototype, "execute")
         .mockImplementation(async function (this: TestWorkflowDefinition) {
@@ -1625,7 +1678,7 @@ describe("WorkflowRuntime", () => {
             resolve(status);
           };
 
-          await instance.create({ definitionVersion: "2026-03-19" });
+          await instance.create();
           await expect(promise).resolves.toBe("completed");
 
           const events = instance.getWorkflowEvents_experimental();
@@ -1646,7 +1699,7 @@ describe("WorkflowRuntime", () => {
       try {
         const stub = env.TEST_WORKFLOW_RUNTIME.getByName(crypto.randomUUID());
         await runInDurableObject(stub, async (instance) => {
-          await instance.create({ definitionVersion: "2026-03-19" });
+          await instance.create();
           await expect.poll(() => instance.getStatus()).toBe("running");
           await instance.pause();
 
@@ -1674,7 +1727,7 @@ describe("WorkflowRuntime", () => {
             resolve(status);
           };
 
-          await instance.create({ definitionVersion: "2026-03-19" });
+          await instance.create();
           await expect.poll(() => instance.getStatus()).toBe("running");
           await instance.pause();
           await instance.resume();
@@ -1706,7 +1759,7 @@ describe("WorkflowRuntime", () => {
             resolve(status);
           };
 
-          await instance.create({ definitionVersion: "2026-03-19" });
+          await instance.create();
           await expect(promise).resolves.toBe("failed");
 
           const events = instance.getWorkflowEvents_experimental();
@@ -1727,7 +1780,7 @@ describe("WorkflowRuntime", () => {
       try {
         const stub = env.TEST_WORKFLOW_RUNTIME.getByName(crypto.randomUUID());
         await runInDurableObject(stub, async (instance) => {
-          await instance.create({ definitionVersion: "2026-03-19" });
+          await instance.create();
           await expect.poll(() => instance.getStatus()).toBe("running");
           await instance.cancel("user requested cancellation");
 
@@ -1761,7 +1814,6 @@ describe("WorkflowRuntime", () => {
     });
   });
 
-
   describe("WorkflowRuntimeContext", () => {
     describe("run steps", () => {
       describe("getOrCreateRunStep()", () => {

package/test/tsconfig.json

@@ -1,10 +1,7 @@
 {
   "extends": "../tsconfig.json",
   "compilerOptions": {
-    "types": [
-      "@cloudflare/vitest-pool-workers",
-      "@cloudflare/workers-types/experimental"
-    ]
+    "types": ["@cloudflare/vitest-pool-workers", "@cloudflare/workers-types/experimental"]
   },
   "include": ["./**/*.ts"],
   "exclude": []

package/test/worker.ts

@@ -6,9 +6,7 @@ export type Env = {
 };
 
 export class TestWorkflowRuntime extends WorkflowRuntime {
-  protected getDefinition() {
-    return this.ctx.exports.TestWorkflowDefinition;
-  }
+  protected readonly definition = this.ctx.exports.TestWorkflowDefinition;
 }
 export class TestWorkflowDefinition extends WorkflowDefinition {
   async execute(): Promise<void> {}