@yolk-sdk/vercel-workflows 0.1.0-canary.63 → 0.1.0-canary.64

package/dist/testing/index.d.mts

@@ -0,0 +1,96 @@
+import { VercelWorkflowReadableOptions, VercelWorkflowReadableStream, VercelWorkflowRunStatus, VercelWorkflowsSdkClient } from "../effect.mjs";
+
+//#region src/testing/index.d.ts
+type TestWorkflowRunStatus = VercelWorkflowRunStatus;
+declare class TestWorkflowStreamConflictError extends Error {
+  readonly name = "EntityConflictError";
+  readonly status = 409;
+  constructor(runId: string);
+}
+declare class TestWorkflowRunConflictError extends Error {
+  readonly name = "EntityConflictError";
+  readonly status = 409;
+  constructor(message: string);
+}
+declare class TestWorkflowHookNotFoundError extends Error {
+  readonly name = "HookNotFoundError";
+  constructor(token: string);
+}
+declare class TestWorkflowHookConflictError extends Error {
+  readonly name = "HookConflictError";
+  constructor(token: string);
+}
+declare class TestWorkflowRunNotFoundError extends Error {
+  readonly name = "WorkflowRunNotFoundError";
+  constructor(runId: string);
+}
+declare class TestWorkflowRunCancelledError extends Error {
+  readonly name = "WorkflowRunCancelledError";
+  constructor(runId: string);
+}
+type TestWorkflowMetadata = {
+  readonly workflowRunId: string;
+};
+type TestWorkflowStepMetadata = {
+  readonly attempt: number;
+  readonly stepId: string;
+  readonly stepName: string;
+};
+type TestWorkflowStepFunction<TArgs extends ReadonlyArray<unknown>, TResult> = ((...args: TArgs) => Promise<TResult>) & {
+  readonly maxRetries?: number;
+};
+declare const defaultTestWorkflowStepMaxRetries = 3;
+type TestWorkflowRunInspection = {
+  readonly runId: string;
+  readonly status: TestWorkflowRunStatus;
+  readonly chunks: ReadonlyArray<unknown>;
+  readonly streamClosed: boolean;
+  readonly streamCloseCount: number;
+  readonly writeAfterCloseAttempts: number;
+  readonly stepAttempts: ReadonlyMap<string, number>;
+  readonly runError: unknown;
+};
+type TestWorkflowHook<T> = Promise<T> & {
+  readonly [Symbol.dispose]: () => void;
+};
+declare class TestWorkflowWorld {
+  private readonly runs;
+  private runSequence;
+  start<TArgs extends ReadonlyArray<unknown>, TResult>(workflowFn: (...args: TArgs) => Promise<TResult>, args: TArgs): {
+    readonly runId: string;
+  };
+  settled(runId: string): Promise<void>;
+  inspect(runId: string): TestWorkflowRunInspection;
+  status(runId: string): TestWorkflowRunStatus;
+  cancel(runId: string): Promise<void>;
+  resumeHook(token: string, payload: unknown): Promise<void>;
+  hasResumedHook(token: string): boolean;
+  runStep<TArgs extends ReadonlyArray<unknown>, TResult>(stepFn: TestWorkflowStepFunction<TArgs, TResult>, args: TArgs, stepName?: string): Promise<TResult>;
+  step<TArgs extends ReadonlyArray<unknown>, TResult>(stepFn: TestWorkflowStepFunction<TArgs, TResult>, stepName?: string): (...args: TArgs) => Promise<TResult>;
+  static getWorkflowMetadata(): TestWorkflowMetadata;
+  static getStepMetadata(): TestWorkflowStepMetadata;
+  static getWritable<T>(): WritableStream<T>;
+  static createHook<T>(input: {
+    readonly token: string;
+  }): TestWorkflowHook<T>;
+  private makeWritable;
+  private makeHook;
+  getReadable<T>(runId: string, options?: VercelWorkflowReadableOptions): VercelWorkflowReadableStream<T>;
+  private streamEnded;
+  private notifyChange;
+  private nextChange;
+  private requireRun;
+  private sdkRun;
+  readonly sdk: VercelWorkflowsSdkClient;
+}
+declare const testWorkflowModule: {
+  getWorkflowMetadata: () => TestWorkflowMetadata;
+  getStepMetadata: () => TestWorkflowStepMetadata;
+  getWritable: <T>() => WritableStream<T>;
+  createHook: <T>(input: {
+    readonly token: string;
+  }) => TestWorkflowHook<T>;
+};
+//#endregion
+export { TestWorkflowHook, TestWorkflowHookConflictError, TestWorkflowHookNotFoundError, TestWorkflowMetadata, TestWorkflowRunCancelledError, TestWorkflowRunConflictError, TestWorkflowRunInspection, TestWorkflowRunNotFoundError, TestWorkflowRunStatus, TestWorkflowStepFunction, TestWorkflowStepMetadata, TestWorkflowStreamConflictError, TestWorkflowWorld, defaultTestWorkflowStepMaxRetries, testWorkflowModule };
+//# sourceMappingURL=index.d.mts.map

package/dist/testing/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/testing/index.ts"],"mappings":";;;KAsBY,qBAAA,GAAwB,uBAAuB;AAAA,cAK9C,+BAAA,SAAwC,KAAK;EAAA,SACtC,IAAA;EAAA,SACT,MAAA;cAEG,KAAA;AAAA;AAAA,cAKD,4BAAA,SAAqC,KAAK;EAAA,SACnC,IAAA;EAAA,SACT,MAAA;cAEG,OAAA;AAAA;AAAA,cAKD,6BAAA,SAAsC,KAAK;EAAA,SACpC,IAAA;cAEN,KAAA;AAAA;AAAA,cAKD,6BAAA,SAAsC,KAAK;EAAA,SACpC,IAAA;cAEN,KAAA;AAAA;AAAA,cAKD,4BAAA,SAAqC,KAAK;EAAA,SACnC,IAAA;cAEN,KAAA;AAAA;AAAA,cAKD,6BAAA,SAAsC,KAAK;EAAA,SACpC,IAAA;cAEN,KAAA;AAAA;AAAA,KAKF,oBAAA;EAAA,SAAkC,aAAa;AAAA;AAAA,KAE/C,wBAAA;EAAA,SACD,OAAA;EAAA,SACA,MAAA;EAAA,SACA,QAAA;AAAA;AAAA,KAGC,wBAAA,eAAuC,aAAA,2BAC9C,IAAA,EAAM,KAAA,KACN,OAAA,CAAQ,OAAA;EAAA,SAAuB,UAAA;AAAA;AAAA,cAGvB,iCAAA;AAAA,KA0CD,yBAAA;EAAA,SACD,KAAA;EAAA,SACA,MAAA,EAAQ,qBAAA;EAAA,SACR,MAAA,EAAQ,aAAA;EAAA,SACR,YAAA;EAAA,SACA,gBAAA;EAAA,SACA,uBAAA;EAAA,SACA,YAAA,EAAc,WAAA;EAAA,SACd,QAAA;AAAA;AAAA,KAGC,gBAAA,MAAsB,OAAA,CAAQ,CAAA;EAAA,UAAiB,MAAA,CAAO,OAAA;AAAA;AAAA,cAErD,iBAAA;EAAA,iBACM,IAAA;EAAA,QACT,WAAA;EAER,KAAA,eAAoB,aAAA,mBAAA,CAClB,UAAA,MAAgB,IAAA,EAAM,KAAA,KAAU,OAAA,CAAQ,OAAA,GACxC,IAAA,EAAM,KAAA;IAAA,SACM,KAAA;EAAA;EA6CR,OAAA,CAAQ,KAAA,WAAgB,OAAA;EAI9B,OAAA,CAAQ,KAAA,WAAgB,yBAAA;EAexB,MAAA,CAAO,KAAA,WAAgB,qBAAA;EAIjB,MAAA,CAAO,KAAA,WAAgB,OAAA;EAiBvB,UAAA,CAAW,KAAA,UAAe,OAAA,YAAmB,OAAA;EAkBnD,cAAA,CAAe,KAAA;EAaT,OAAA,eAAsB,aAAA,mBAAA,CAC1B,MAAA,EAAQ,wBAAA,CAAyB,KAAA,EAAO,OAAA,GACxC,IAAA,EAAM,KAAA,EACN,QAAA,YACC,OAAA,CAAQ,OAAA;EA0BX,IAAA,eAAmB,aAAA,mBAAA,CACjB,MAAA,EAAQ,wBAAA,CAAyB,KAAA,EAAO,OAAA,GACxC,QAAA,gBACK,IAAA,EAAM,KAAA,KAAU,OAAA,CAAQ,OAAA;EAAA,OAMxB,mBAAA,CAAA,GAAuB,oBAAA;EAAA,OAIvB,eAAA,CAAA,GAAmB,wBAAA;EAAA,OAUnB,WAAA,GAAA,CAAA,GAAkB,cAAA,CAAe,CAAA;EAAA,OAMjC,UAAA,GAAA,CAAc,KAAA;IAAA,SAAkB,KAAA;EAAA,IAAkB,gBAAA,CAAiB,CAAA;EAAA,QAQlE,YAAA;EAAA,QAwBA,QAAA;EAmBR,WAAA,GAAA,CACE,KAAA,UACA,OAAA,GAAU,6BAAA,GACT,4BAAA,CAA6B,CAAA;EAAA,QA+BxB,WAAA;EAAA,QAIA,YAAA;EAAA,QAMA,UAAA;EAAA,QAMA,UAAA;EAAA,QAUA,MAAA;EAAA,SAwBC,GAAA,EAAK,wBAAA;AAAA;AAAA,cAcH,kBAAA;;;wBAGI,cAAA,CAAA,CAAA;kBACD,KAAA;IAAA,SAAoB,KAAA;EAAA,MAAe,gBAAA,CAAA,CAAA;AAAA"}

package/dist/testing/index.mjs

@@ -0,0 +1,285 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/testing/index.ts
+var TestWorkflowStreamConflictError = class extends Error {
+	name = "EntityConflictError";
+	status = 409;
+	constructor(runId) {
+		super(`Workflow run "${runId}" stream already completed`);
+	}
+};
+var TestWorkflowRunConflictError = class extends Error {
+	name = "EntityConflictError";
+	status = 409;
+	constructor(message) {
+		super(message);
+	}
+};
+var TestWorkflowHookNotFoundError = class extends Error {
+	name = "HookNotFoundError";
+	constructor(token) {
+		super(`Workflow hook "${token}" was not found`);
+	}
+};
+var TestWorkflowHookConflictError = class extends Error {
+	name = "HookConflictError";
+	constructor(token) {
+		super(`Workflow hook "${token}" was already resumed`);
+	}
+};
+var TestWorkflowRunNotFoundError = class extends Error {
+	name = "WorkflowRunNotFoundError";
+	constructor(runId) {
+		super(`Workflow run "${runId}" was not found`);
+	}
+};
+var TestWorkflowRunCancelledError = class extends Error {
+	name = "WorkflowRunCancelledError";
+	constructor(runId) {
+		super(`Workflow run "${runId}" was cancelled`);
+	}
+};
+const defaultTestWorkflowStepMaxRetries = 3;
+const ambientStorage = new AsyncLocalStorage();
+const requireAmbient = () => {
+	const ambient = ambientStorage.getStore();
+	if (ambient === void 0) throw new Error("Workflow ambient API called outside a TestWorkflowWorld run context");
+	return ambient;
+};
+var TestWorkflowWorld = class {
+	runs = /* @__PURE__ */ new Map();
+	runSequence = 0;
+	start(workflowFn, args) {
+		this.runSequence += 1;
+		const runId = `twr_${this.runSequence}`;
+		const run = {
+			runId,
+			status: "pending",
+			returnValue: void 0,
+			runError: void 0,
+			settled: Promise.resolve(),
+			chunks: [],
+			streamClosed: false,
+			streamCloseCount: 0,
+			writeAfterCloseAttempts: 0,
+			changeListeners: /* @__PURE__ */ new Set(),
+			hooks: /* @__PURE__ */ new Map(),
+			resumedHookTokens: /* @__PURE__ */ new Set(),
+			stepSequence: 0,
+			stepAttempts: /* @__PURE__ */ new Map()
+		};
+		this.runs.set(runId, run);
+		run.settled = ambientStorage.run({
+			world: this,
+			run,
+			stepMetadata: void 0
+		}, async () => {
+			await Promise.resolve();
+			if (run.status === "cancelled") return;
+			run.status = "running";
+			try {
+				run.returnValue = await workflowFn(...args);
+				if (run.status === "running") run.status = "completed";
+			} catch (error) {
+				run.runError = error;
+				if (run.status === "running") run.status = "failed";
+			} finally {
+				this.notifyChange(run);
+			}
+		});
+		return { runId };
+	}
+	async settled(runId) {
+		await this.requireRun(runId).settled;
+	}
+	inspect(runId) {
+		const run = this.requireRun(runId);
+		return {
+			runId: run.runId,
+			status: run.status,
+			chunks: [...run.chunks],
+			streamClosed: run.streamClosed,
+			streamCloseCount: run.streamCloseCount,
+			writeAfterCloseAttempts: run.writeAfterCloseAttempts,
+			stepAttempts: new Map(run.stepAttempts),
+			runError: run.runError
+		};
+	}
+	status(runId) {
+		return this.requireRun(runId).status;
+	}
+	async cancel(runId) {
+		const run = this.requireRun(runId);
+		if (run.status === "completed" || run.status === "failed" || run.status === "cancelled") throw new TestWorkflowRunConflictError(`Workflow run "${runId}" is already ${run.status} and cannot be cancelled`);
+		run.status = "cancelled";
+		for (const [token, hook] of run.hooks) {
+			run.hooks.delete(token);
+			hook.reject(new TestWorkflowRunCancelledError(runId));
+		}
+		this.notifyChange(run);
+	}
+	async resumeHook(token, payload) {
+		for (const run of this.runs.values()) {
+			const hook = run.hooks.get(token);
+			if (hook !== void 0) {
+				run.hooks.delete(token);
+				run.resumedHookTokens.add(token);
+				hook.resolve(payload);
+				return;
+			}
+			if (run.resumedHookTokens.has(token)) throw new TestWorkflowHookConflictError(token);
+		}
+		throw new TestWorkflowHookNotFoundError(token);
+	}
+	hasResumedHook(token) {
+		for (const run of this.runs.values()) if (run.resumedHookTokens.has(token)) return true;
+		return false;
+	}
+	async runStep(stepFn, args, stepName = stepFn.name === "" ? "step" : stepFn.name) {
+		const run = requireAmbient().run;
+		run.stepSequence += 1;
+		const stepId = `${run.runId}:step:${run.stepSequence}:${stepName}`;
+		const maxAttempts = (stepFn.maxRetries ?? 3) + 1;
+		let attempt = 1;
+		for (;;) {
+			run.stepAttempts.set(stepName, (run.stepAttempts.get(stepName) ?? 0) + 1);
+			try {
+				return await ambientStorage.run({
+					world: this,
+					run,
+					stepMetadata: {
+						attempt,
+						stepId,
+						stepName
+					}
+				}, () => stepFn(...args));
+			} catch (error) {
+				if (attempt >= maxAttempts) throw error;
+				attempt += 1;
+			}
+		}
+	}
+	step(stepFn, stepName) {
+		return (...args) => this.runStep(stepFn, args, stepName);
+	}
+	static getWorkflowMetadata() {
+		return { workflowRunId: requireAmbient().run.runId };
+	}
+	static getStepMetadata() {
+		const ambient = requireAmbient();
+		if (ambient.stepMetadata === void 0) throw new Error("getStepMetadata called outside a step context");
+		return ambient.stepMetadata;
+	}
+	static getWritable() {
+		const ambient = requireAmbient();
+		return ambient.world.makeWritable(ambient.run);
+	}
+	static createHook(input) {
+		const ambient = requireAmbient();
+		return ambient.world.makeHook(ambient.run, input.token);
+	}
+	makeWritable(run) {
+		return new WritableStream({
+			write: (chunk) => {
+				if (run.streamClosed || run.status === "cancelled") {
+					run.writeAfterCloseAttempts += 1;
+					throw new TestWorkflowStreamConflictError(run.runId);
+				}
+				run.chunks.push(chunk);
+				this.notifyChange(run);
+			},
+			close: () => {
+				if (run.streamClosed) {
+					run.streamCloseCount += 1;
+					throw new TestWorkflowStreamConflictError(run.runId);
+				}
+				run.streamClosed = true;
+				run.streamCloseCount += 1;
+				this.notifyChange(run);
+			}
+		});
+	}
+	makeHook(run, token) {
+		let resolveHook = () => {};
+		let rejectHook = () => {};
+		const promise = new Promise((resolve, reject) => {
+			resolveHook = (payload) => resolve(payload);
+			rejectHook = reject;
+		});
+		run.hooks.set(token, {
+			resolve: resolveHook,
+			reject: rejectHook
+		});
+		return Object.assign(promise, { [Symbol.dispose]: () => {
+			run.hooks.delete(token);
+		} });
+	}
+	getReadable(runId, options) {
+		const run = this.requireRun(runId);
+		const requestedStart = options?.startIndex ?? 0;
+		let index = requestedStart < 0 ? Math.max(0, run.chunks.length + requestedStart) : requestedStart;
+		const stream = new ReadableStream({ pull: async (controller) => {
+			while (index >= run.chunks.length && !this.streamEnded(run)) await this.nextChange(run);
+			if (index < run.chunks.length) {
+				controller.enqueue(run.chunks[index]);
+				index += 1;
+				return;
+			}
+			controller.close();
+		} });
+		return Object.assign(stream, { getTailIndex: () => Promise.resolve(run.chunks.length - 1) });
+	}
+	streamEnded(run) {
+		return run.streamClosed || run.status === "cancelled";
+	}
+	notifyChange(run) {
+		const listeners = [...run.changeListeners];
+		run.changeListeners.clear();
+		for (const listener of listeners) listener();
+	}
+	nextChange(run) {
+		return new Promise((resolve) => {
+			run.changeListeners.add(resolve);
+		});
+	}
+	requireRun(runId) {
+		const run = this.runs.get(runId);
+		if (run === void 0) throw new TestWorkflowRunNotFoundError(runId);
+		return run;
+	}
+	sdkRun(run) {
+		const getReadable = (options) => this.getReadable(run.runId, options);
+		const cancel = () => this.cancel(run.runId);
+		return {
+			runId: run.runId,
+			getReadable,
+			cancel,
+			get status() {
+				return Promise.resolve(run.status);
+			},
+			get returnValue() {
+				return run.settled.then(() => {
+					if (run.status === "completed") return run.returnValue;
+					throw run.runError ?? new TestWorkflowRunCancelledError(run.runId);
+				});
+			}
+		};
+	}
+	sdk = {
+		start: async (workflowFn, args) => {
+			const { runId } = this.start(workflowFn, args);
+			return this.sdkRun(this.requireRun(runId));
+		},
+		getRun: (runId) => this.sdkRun(this.requireRun(runId)),
+		resumeHook: (token, payload) => this.resumeHook(token, payload)
+	};
+};
+const testWorkflowModule = {
+	getWorkflowMetadata: () => TestWorkflowWorld.getWorkflowMetadata(),
+	getStepMetadata: () => TestWorkflowWorld.getStepMetadata(),
+	getWritable: () => TestWorkflowWorld.getWritable(),
+	createHook: (input) => TestWorkflowWorld.createHook(input)
+};
+//#endregion
+export { TestWorkflowHookConflictError, TestWorkflowHookNotFoundError, TestWorkflowRunCancelledError, TestWorkflowRunConflictError, TestWorkflowRunNotFoundError, TestWorkflowStreamConflictError, TestWorkflowWorld, defaultTestWorkflowStepMaxRetries, testWorkflowModule };
+
+//# sourceMappingURL=index.mjs.map

package/dist/testing/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/testing/index.ts"],"sourcesContent":["import { AsyncLocalStorage } from 'node:async_hooks'\nimport type {\n  VercelWorkflowsSdkClient,\n  VercelWorkflowsSdkRun,\n  VercelWorkflowReadableOptions,\n  VercelWorkflowReadableStream,\n  VercelWorkflowRunStatus\n} from '../effect.ts'\n\n// Behavioral emulator of the Vercel Workflow platform for tests: run lifecycle,\n// append-only durable streams with close-once -> 409 write conflicts, a step\n// executor honoring `fn.maxRetries` + `getStepMetadata().attempt`, hooks/resume,\n// and cancellation. Host code under test runs unmodified against it; tests mock\n// only the `workflow` module's ambient APIs, delegating to the active world\n// (see `testWorkflowModule`).\n//\n// The single most important semantic: writing to (or re-closing) a closed\n// durable stream fails with the platform's HTTP 409 \"already completed\"\n// conflict shape. Any code path that performs a terminal stream effect from a\n// retryable step attempt poisons every subsequent platform retry — exactly the\n// #252 production bug. The emulator enforces that invariant permanently.\n\nexport type TestWorkflowRunStatus = VercelWorkflowRunStatus\n\n// Matches the platform's conflict contract: `EntityConflictError.is(value)`\n// checks `value.name === 'EntityConflictError'`, and the Vercel world maps\n// HTTP 409 responses to that class.\nexport class TestWorkflowStreamConflictError extends Error {\n  override readonly name = 'EntityConflictError'\n  readonly status = 409\n\n  constructor(runId: string) {\n    super(`Workflow run \"${runId}\" stream already completed`)\n  }\n}\n\nexport class TestWorkflowRunConflictError extends Error {\n  override readonly name = 'EntityConflictError'\n  readonly status = 409\n\n  constructor(message: string) {\n    super(message)\n  }\n}\n\nexport class TestWorkflowHookNotFoundError extends Error {\n  override readonly name = 'HookNotFoundError'\n\n  constructor(token: string) {\n    super(`Workflow hook \"${token}\" was not found`)\n  }\n}\n\nexport class TestWorkflowHookConflictError extends Error {\n  override readonly name = 'HookConflictError'\n\n  constructor(token: string) {\n    super(`Workflow hook \"${token}\" was already resumed`)\n  }\n}\n\nexport class TestWorkflowRunNotFoundError extends Error {\n  override readonly name = 'WorkflowRunNotFoundError'\n\n  constructor(runId: string) {\n    super(`Workflow run \"${runId}\" was not found`)\n  }\n}\n\nexport class TestWorkflowRunCancelledError extends Error {\n  override readonly name = 'WorkflowRunCancelledError'\n\n  constructor(runId: string) {\n    super(`Workflow run \"${runId}\" was cancelled`)\n  }\n}\n\nexport type TestWorkflowMetadata = { readonly workflowRunId: string }\n\nexport type TestWorkflowStepMetadata = {\n  readonly attempt: number\n  readonly stepId: string\n  readonly stepName: string\n}\n\nexport type TestWorkflowStepFunction<TArgs extends ReadonlyArray<unknown>, TResult> = ((\n  ...args: TArgs\n) => Promise<TResult>) & { readonly maxRetries?: number }\n\n// The platform default: retries after the first attempt; total attempts = maxRetries + 1.\nexport const defaultTestWorkflowStepMaxRetries = 3\n\ntype HookRecord = {\n  readonly resolve: (payload: unknown) => void\n  readonly reject: (error: unknown) => void\n}\n\ntype TestWorkflowRunRecord = {\n  readonly runId: string\n  status: TestWorkflowRunStatus\n  returnValue: unknown\n  runError: unknown\n  settled: Promise<void>\n  readonly chunks: Array<unknown>\n  streamClosed: boolean\n  streamCloseCount: number\n  writeAfterCloseAttempts: number\n  readonly changeListeners: Set<() => void>\n  readonly hooks: Map<string, HookRecord>\n  readonly resumedHookTokens: Set<string>\n  stepSequence: number\n  readonly stepAttempts: Map<string, number>\n}\n\ntype AmbientContext = {\n  readonly world: TestWorkflowWorld\n  readonly run: TestWorkflowRunRecord\n  readonly stepMetadata: TestWorkflowStepMetadata | undefined\n}\n\nconst ambientStorage = new AsyncLocalStorage<AmbientContext>()\n\nconst requireAmbient = (): AmbientContext => {\n  const ambient = ambientStorage.getStore()\n\n  if (ambient === undefined) {\n    throw new Error('Workflow ambient API called outside a TestWorkflowWorld run context')\n  }\n\n  return ambient\n}\n\nexport type TestWorkflowRunInspection = {\n  readonly runId: string\n  readonly status: TestWorkflowRunStatus\n  readonly chunks: ReadonlyArray<unknown>\n  readonly streamClosed: boolean\n  readonly streamCloseCount: number\n  readonly writeAfterCloseAttempts: number\n  readonly stepAttempts: ReadonlyMap<string, number>\n  readonly runError: unknown\n}\n\nexport type TestWorkflowHook<T> = Promise<T> & { readonly [Symbol.dispose]: () => void }\n\nexport class TestWorkflowWorld {\n  private readonly runs = new Map<string, TestWorkflowRunRecord>()\n  private runSequence = 0\n\n  start<TArgs extends ReadonlyArray<unknown>, TResult>(\n    workflowFn: (...args: TArgs) => Promise<TResult>,\n    args: TArgs\n  ): { readonly runId: string } {\n    this.runSequence += 1\n    const runId = `twr_${this.runSequence}`\n    const run: TestWorkflowRunRecord = {\n      runId,\n      status: 'pending',\n      returnValue: undefined,\n      runError: undefined,\n      settled: Promise.resolve(),\n      chunks: [],\n      streamClosed: false,\n      streamCloseCount: 0,\n      writeAfterCloseAttempts: 0,\n      changeListeners: new Set(),\n      hooks: new Map(),\n      resumedHookTokens: new Set(),\n      stepSequence: 0,\n      stepAttempts: new Map()\n    }\n    this.runs.set(runId, run)\n\n    run.settled = ambientStorage.run(\n      { world: this, run, stepMetadata: undefined },\n      async (): Promise<void> => {\n        // Yield once so callers observe `pending` before execution begins,\n        // mirroring the platform's enqueue-then-run lifecycle.\n        await Promise.resolve()\n        if (run.status === 'cancelled') return\n\n        run.status = 'running'\n        try {\n          run.returnValue = await workflowFn(...args)\n          if (run.status === 'running') run.status = 'completed'\n        } catch (error) {\n          run.runError = error\n          if (run.status === 'running') run.status = 'failed'\n        } finally {\n          this.notifyChange(run)\n        }\n      }\n    )\n\n    return { runId }\n  }\n\n  async settled(runId: string): Promise<void> {\n    await this.requireRun(runId).settled\n  }\n\n  inspect(runId: string): TestWorkflowRunInspection {\n    const run = this.requireRun(runId)\n\n    return {\n      runId: run.runId,\n      status: run.status,\n      chunks: [...run.chunks],\n      streamClosed: run.streamClosed,\n      streamCloseCount: run.streamCloseCount,\n      writeAfterCloseAttempts: run.writeAfterCloseAttempts,\n      stepAttempts: new Map(run.stepAttempts),\n      runError: run.runError\n    }\n  }\n\n  status(runId: string): TestWorkflowRunStatus {\n    return this.requireRun(runId).status\n  }\n\n  async cancel(runId: string): Promise<void> {\n    const run = this.requireRun(runId)\n\n    if (run.status === 'completed' || run.status === 'failed' || run.status === 'cancelled') {\n      throw new TestWorkflowRunConflictError(\n        `Workflow run \"${runId}\" is already ${run.status} and cannot be cancelled`\n      )\n    }\n\n    run.status = 'cancelled'\n    for (const [token, hook] of run.hooks) {\n      run.hooks.delete(token)\n      hook.reject(new TestWorkflowRunCancelledError(runId))\n    }\n    this.notifyChange(run)\n  }\n\n  async resumeHook(token: string, payload: unknown): Promise<void> {\n    for (const run of this.runs.values()) {\n      const hook = run.hooks.get(token)\n      if (hook !== undefined) {\n        run.hooks.delete(token)\n        run.resumedHookTokens.add(token)\n        hook.resolve(payload)\n        return\n      }\n\n      if (run.resumedHookTokens.has(token)) {\n        throw new TestWorkflowHookConflictError(token)\n      }\n    }\n\n    throw new TestWorkflowHookNotFoundError(token)\n  }\n\n  hasResumedHook(token: string): boolean {\n    for (const run of this.runs.values()) {\n      if (run.resumedHookTokens.has(token)) return true\n    }\n\n    return false\n  }\n\n  // --- Step executor (platform retry semantics) ---\n\n  // Runs a step body with the platform's retry contract: `fn.maxRetries`\n  // retries after the first attempt (total attempts = maxRetries + 1) and\n  // 1-based `getStepMetadata().attempt` visible to the body.\n  async runStep<TArgs extends ReadonlyArray<unknown>, TResult>(\n    stepFn: TestWorkflowStepFunction<TArgs, TResult>,\n    args: TArgs,\n    stepName = stepFn.name === '' ? 'step' : stepFn.name\n  ): Promise<TResult> {\n    const ambient = requireAmbient()\n    const run = ambient.run\n    run.stepSequence += 1\n    const stepId = `${run.runId}:step:${run.stepSequence}:${stepName}`\n    const maxRetries = stepFn.maxRetries ?? defaultTestWorkflowStepMaxRetries\n    const maxAttempts = maxRetries + 1\n\n    let attempt = 1\n\n    for (;;) {\n      run.stepAttempts.set(stepName, (run.stepAttempts.get(stepName) ?? 0) + 1)\n      try {\n        return await ambientStorage.run(\n          { world: this, run, stepMetadata: { attempt, stepId, stepName } },\n          () => stepFn(...args)\n        )\n      } catch (error) {\n        if (attempt >= maxAttempts) throw error\n        attempt += 1\n      }\n    }\n  }\n\n  // Wraps a step function so orchestration code can invoke it exactly the way\n  // the platform invokes `use step` functions: through the retry executor.\n  step<TArgs extends ReadonlyArray<unknown>, TResult>(\n    stepFn: TestWorkflowStepFunction<TArgs, TResult>,\n    stepName?: string\n  ): (...args: TArgs) => Promise<TResult> {\n    return (...args: TArgs) => this.runStep(stepFn, args, stepName)\n  }\n\n  // --- Ambient platform APIs (exposed through `testWorkflowModule`) ---\n\n  static getWorkflowMetadata(): TestWorkflowMetadata {\n    return { workflowRunId: requireAmbient().run.runId }\n  }\n\n  static getStepMetadata(): TestWorkflowStepMetadata {\n    const ambient = requireAmbient()\n\n    if (ambient.stepMetadata === undefined) {\n      throw new Error('getStepMetadata called outside a step context')\n    }\n\n    return ambient.stepMetadata\n  }\n\n  static getWritable<T>(): WritableStream<T> {\n    const ambient = requireAmbient()\n\n    return ambient.world.makeWritable(ambient.run)\n  }\n\n  static createHook<T>(input: { readonly token: string }): TestWorkflowHook<T> {\n    const ambient = requireAmbient()\n\n    return ambient.world.makeHook<T>(ambient.run, input.token)\n  }\n\n  // --- Durable streams ---\n\n  private makeWritable<T>(run: TestWorkflowRunRecord): WritableStream<T> {\n    return new WritableStream<T>({\n      write: chunk => {\n        if (run.streamClosed || run.status === 'cancelled') {\n          run.writeAfterCloseAttempts += 1\n          throw new TestWorkflowStreamConflictError(run.runId)\n        }\n\n        run.chunks.push(chunk)\n        this.notifyChange(run)\n      },\n      close: () => {\n        if (run.streamClosed) {\n          run.streamCloseCount += 1\n          throw new TestWorkflowStreamConflictError(run.runId)\n        }\n\n        run.streamClosed = true\n        run.streamCloseCount += 1\n        this.notifyChange(run)\n      }\n    })\n  }\n\n  private makeHook<T>(run: TestWorkflowRunRecord, token: string): TestWorkflowHook<T> {\n    let resolveHook: (payload: unknown) => void = () => {}\n    let rejectHook: (error: unknown) => void = () => {}\n    const promise = new Promise<T>((resolve, reject) => {\n      // Hook payloads are caller-typed on the platform (`createHook<T>`).\n      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n      resolveHook = payload => resolve(payload as T)\n      rejectHook = reject\n    })\n\n    run.hooks.set(token, { resolve: resolveHook, reject: rejectHook })\n\n    return Object.assign(promise, {\n      [Symbol.dispose]: () => {\n        run.hooks.delete(token)\n      }\n    })\n  }\n\n  getReadable<T>(\n    runId: string,\n    options?: VercelWorkflowReadableOptions\n  ): VercelWorkflowReadableStream<T> {\n    const run = this.requireRun(runId)\n    const requestedStart = options?.startIndex ?? 0\n    let index =\n      requestedStart < 0 ? Math.max(0, run.chunks.length + requestedStart) : requestedStart\n\n    const stream = new ReadableStream<T>({\n      pull: async controller => {\n        while (index >= run.chunks.length && !this.streamEnded(run)) {\n          await this.nextChange(run)\n        }\n\n        if (index < run.chunks.length) {\n          // The platform readable is caller-typed (`WorkflowReadableStream<R = any>`);\n          // the durable log stores opaque chunks, so this coercion mirrors the\n          // platform contract exactly.\n          // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n          controller.enqueue(run.chunks[index] as T)\n          index += 1\n          return\n        }\n\n        controller.close()\n      }\n    })\n\n    return Object.assign(stream, {\n      getTailIndex: () => Promise.resolve(run.chunks.length - 1)\n    })\n  }\n\n  private streamEnded(run: TestWorkflowRunRecord): boolean {\n    return run.streamClosed || run.status === 'cancelled'\n  }\n\n  private notifyChange(run: TestWorkflowRunRecord): void {\n    const listeners = [...run.changeListeners]\n    run.changeListeners.clear()\n    for (const listener of listeners) listener()\n  }\n\n  private nextChange(run: TestWorkflowRunRecord): Promise<void> {\n    return new Promise(resolve => {\n      run.changeListeners.add(resolve)\n    })\n  }\n\n  private requireRun(runId: string): TestWorkflowRunRecord {\n    const run = this.runs.get(runId)\n\n    if (run === undefined) throw new TestWorkflowRunNotFoundError(runId)\n\n    return run\n  }\n\n  // --- SDK adapter for `VercelWorkflows.layerFromSdk` ---\n\n  private sdkRun<TResult>(run: TestWorkflowRunRecord): VercelWorkflowsSdkRun<TResult> {\n    const getReadable = <Chunk>(options?: VercelWorkflowReadableOptions) =>\n      this.getReadable<Chunk>(run.runId, options)\n    const cancel = () => this.cancel(run.runId)\n\n    return {\n      runId: run.runId,\n      getReadable,\n      cancel,\n      get status() {\n        return Promise.resolve(run.status)\n      },\n      get returnValue() {\n        return run.settled.then(() => {\n          // Return values are caller-typed on the platform SDK as well.\n          // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n          if (run.status === 'completed') return run.returnValue as TResult\n\n          throw run.runError ?? new TestWorkflowRunCancelledError(run.runId)\n        })\n      }\n    }\n  }\n\n  readonly sdk: VercelWorkflowsSdkClient = {\n    start: async (workflowFn, args) => {\n      const { runId } = this.start(workflowFn, args)\n\n      return this.sdkRun(this.requireRun(runId))\n    },\n    getRun: <TResult>(runId: string) => this.sdkRun<TResult>(this.requireRun(runId)),\n    resumeHook: (token, payload) => this.resumeHook(token, payload)\n  }\n}\n\n// Factory for `vi.mock('workflow', () => testWorkflowModule)`: the mocked\n// module surface delegates every ambient platform API to the active world's\n// AsyncLocalStorage context, so production code under test runs unmodified.\nexport const testWorkflowModule = {\n  getWorkflowMetadata: () => TestWorkflowWorld.getWorkflowMetadata(),\n  getStepMetadata: () => TestWorkflowWorld.getStepMetadata(),\n  getWritable: <T>() => TestWorkflowWorld.getWritable<T>(),\n  createHook: <T>(input: { readonly token: string }) => TestWorkflowWorld.createHook<T>(input)\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yolk-sdk/vercel-workflows",
-  "version": "0.1.0-canary.63",
+  "version": "0.1.0-canary.64",
   "description": "Vercel Workflow orchestration primitives for Yolk agent loops.",
   "license": "MIT",
   "type": "module",
@@ -40,6 +40,11 @@
       "types": "./dist/effect.d.mts",
       "import": "./dist/effect.mjs",
       "default": "./dist/effect.mjs"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.mts",
+      "import": "./dist/testing/index.mjs",
+      "default": "./dist/testing/index.mjs"
     }
   },
   "files": [

package/src/testing/index.ts

@@ -0,0 +1,482 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import type {
+  VercelWorkflowsSdkClient,
+  VercelWorkflowsSdkRun,
+  VercelWorkflowReadableOptions,
+  VercelWorkflowReadableStream,
+  VercelWorkflowRunStatus
+} from '../effect.ts'
+
+// Behavioral emulator of the Vercel Workflow platform for tests: run lifecycle,
+// append-only durable streams with close-once -> 409 write conflicts, a step
+// executor honoring `fn.maxRetries` + `getStepMetadata().attempt`, hooks/resume,
+// and cancellation. Host code under test runs unmodified against it; tests mock
+// only the `workflow` module's ambient APIs, delegating to the active world
+// (see `testWorkflowModule`).
+//
+// The single most important semantic: writing to (or re-closing) a closed
+// durable stream fails with the platform's HTTP 409 "already completed"
+// conflict shape. Any code path that performs a terminal stream effect from a
+// retryable step attempt poisons every subsequent platform retry — exactly the
+// #252 production bug. The emulator enforces that invariant permanently.
+
+export type TestWorkflowRunStatus = VercelWorkflowRunStatus
+
+// Matches the platform's conflict contract: `EntityConflictError.is(value)`
+// checks `value.name === 'EntityConflictError'`, and the Vercel world maps
+// HTTP 409 responses to that class.
+export class TestWorkflowStreamConflictError extends Error {
+  override readonly name = 'EntityConflictError'
+  readonly status = 409
+
+  constructor(runId: string) {
+    super(`Workflow run "${runId}" stream already completed`)
+  }
+}
+
+export class TestWorkflowRunConflictError extends Error {
+  override readonly name = 'EntityConflictError'
+  readonly status = 409
+
+  constructor(message: string) {
+    super(message)
+  }
+}
+
+export class TestWorkflowHookNotFoundError extends Error {
+  override readonly name = 'HookNotFoundError'
+
+  constructor(token: string) {
+    super(`Workflow hook "${token}" was not found`)
+  }
+}
+
+export class TestWorkflowHookConflictError extends Error {
+  override readonly name = 'HookConflictError'
+
+  constructor(token: string) {
+    super(`Workflow hook "${token}" was already resumed`)
+  }
+}
+
+export class TestWorkflowRunNotFoundError extends Error {
+  override readonly name = 'WorkflowRunNotFoundError'
+
+  constructor(runId: string) {
+    super(`Workflow run "${runId}" was not found`)
+  }
+}
+
+export class TestWorkflowRunCancelledError extends Error {
+  override readonly name = 'WorkflowRunCancelledError'
+
+  constructor(runId: string) {
+    super(`Workflow run "${runId}" was cancelled`)
+  }
+}
+
+export type TestWorkflowMetadata = { readonly workflowRunId: string }
+
+export type TestWorkflowStepMetadata = {
+  readonly attempt: number
+  readonly stepId: string
+  readonly stepName: string
+}
+
+export type TestWorkflowStepFunction<TArgs extends ReadonlyArray<unknown>, TResult> = ((
+  ...args: TArgs
+) => Promise<TResult>) & { readonly maxRetries?: number }
+
+// The platform default: retries after the first attempt; total attempts = maxRetries + 1.
+export const defaultTestWorkflowStepMaxRetries = 3
+
+type HookRecord = {
+  readonly resolve: (payload: unknown) => void
+  readonly reject: (error: unknown) => void
+}
+
+type TestWorkflowRunRecord = {
+  readonly runId: string
+  status: TestWorkflowRunStatus
+  returnValue: unknown
+  runError: unknown
+  settled: Promise<void>
+  readonly chunks: Array<unknown>
+  streamClosed: boolean
+  streamCloseCount: number
+  writeAfterCloseAttempts: number
+  readonly changeListeners: Set<() => void>
+  readonly hooks: Map<string, HookRecord>
+  readonly resumedHookTokens: Set<string>
+  stepSequence: number
+  readonly stepAttempts: Map<string, number>
+}
+
+type AmbientContext = {
+  readonly world: TestWorkflowWorld
+  readonly run: TestWorkflowRunRecord
+  readonly stepMetadata: TestWorkflowStepMetadata | undefined
+}
+
+const ambientStorage = new AsyncLocalStorage<AmbientContext>()
+
+const requireAmbient = (): AmbientContext => {
+  const ambient = ambientStorage.getStore()
+
+  if (ambient === undefined) {
+    throw new Error('Workflow ambient API called outside a TestWorkflowWorld run context')
+  }
+
+  return ambient
+}
+
+export type TestWorkflowRunInspection = {
+  readonly runId: string
+  readonly status: TestWorkflowRunStatus
+  readonly chunks: ReadonlyArray<unknown>
+  readonly streamClosed: boolean
+  readonly streamCloseCount: number
+  readonly writeAfterCloseAttempts: number
+  readonly stepAttempts: ReadonlyMap<string, number>
+  readonly runError: unknown
+}
+
+export type TestWorkflowHook<T> = Promise<T> & { readonly [Symbol.dispose]: () => void }
+
+export class TestWorkflowWorld {
+  private readonly runs = new Map<string, TestWorkflowRunRecord>()
+  private runSequence = 0
+
+  start<TArgs extends ReadonlyArray<unknown>, TResult>(
+    workflowFn: (...args: TArgs) => Promise<TResult>,
+    args: TArgs
+  ): { readonly runId: string } {
+    this.runSequence += 1
+    const runId = `twr_${this.runSequence}`
+    const run: TestWorkflowRunRecord = {
+      runId,
+      status: 'pending',
+      returnValue: undefined,
+      runError: undefined,
+      settled: Promise.resolve(),
+      chunks: [],
+      streamClosed: false,
+      streamCloseCount: 0,
+      writeAfterCloseAttempts: 0,
+      changeListeners: new Set(),
+      hooks: new Map(),
+      resumedHookTokens: new Set(),
+      stepSequence: 0,
+      stepAttempts: new Map()
+    }
+    this.runs.set(runId, run)
+
+    run.settled = ambientStorage.run(
+      { world: this, run, stepMetadata: undefined },
+      async (): Promise<void> => {
+        // Yield once so callers observe `pending` before execution begins,
+        // mirroring the platform's enqueue-then-run lifecycle.
+        await Promise.resolve()
+        if (run.status === 'cancelled') return
+
+        run.status = 'running'
+        try {
+          run.returnValue = await workflowFn(...args)
+          if (run.status === 'running') run.status = 'completed'
+        } catch (error) {
+          run.runError = error
+          if (run.status === 'running') run.status = 'failed'
+        } finally {
+          this.notifyChange(run)
+        }
+      }
+    )
+
+    return { runId }
+  }
+
+  async settled(runId: string): Promise<void> {
+    await this.requireRun(runId).settled
+  }
+
+  inspect(runId: string): TestWorkflowRunInspection {
+    const run = this.requireRun(runId)
+
+    return {
+      runId: run.runId,
+      status: run.status,
+      chunks: [...run.chunks],
+      streamClosed: run.streamClosed,
+      streamCloseCount: run.streamCloseCount,
+      writeAfterCloseAttempts: run.writeAfterCloseAttempts,
+      stepAttempts: new Map(run.stepAttempts),
+      runError: run.runError
+    }
+  }
+
+  status(runId: string): TestWorkflowRunStatus {
+    return this.requireRun(runId).status
+  }
+
+  async cancel(runId: string): Promise<void> {
+    const run = this.requireRun(runId)
+
+    if (run.status === 'completed' || run.status === 'failed' || run.status === 'cancelled') {
+      throw new TestWorkflowRunConflictError(
+        `Workflow run "${runId}" is already ${run.status} and cannot be cancelled`
+      )
+    }
+
+    run.status = 'cancelled'
+    for (const [token, hook] of run.hooks) {
+      run.hooks.delete(token)
+      hook.reject(new TestWorkflowRunCancelledError(runId))
+    }
+    this.notifyChange(run)
+  }
+
+  async resumeHook(token: string, payload: unknown): Promise<void> {
+    for (const run of this.runs.values()) {
+      const hook = run.hooks.get(token)
+      if (hook !== undefined) {
+        run.hooks.delete(token)
+        run.resumedHookTokens.add(token)
+        hook.resolve(payload)
+        return
+      }
+
+      if (run.resumedHookTokens.has(token)) {
+        throw new TestWorkflowHookConflictError(token)
+      }
+    }
+
+    throw new TestWorkflowHookNotFoundError(token)
+  }
+
+  hasResumedHook(token: string): boolean {
+    for (const run of this.runs.values()) {
+      if (run.resumedHookTokens.has(token)) return true
+    }
+
+    return false
+  }
+
+  // --- Step executor (platform retry semantics) ---
+
+  // Runs a step body with the platform's retry contract: `fn.maxRetries`
+  // retries after the first attempt (total attempts = maxRetries + 1) and
+  // 1-based `getStepMetadata().attempt` visible to the body.
+  async runStep<TArgs extends ReadonlyArray<unknown>, TResult>(
+    stepFn: TestWorkflowStepFunction<TArgs, TResult>,
+    args: TArgs,
+    stepName = stepFn.name === '' ? 'step' : stepFn.name
+  ): Promise<TResult> {
+    const ambient = requireAmbient()
+    const run = ambient.run
+    run.stepSequence += 1
+    const stepId = `${run.runId}:step:${run.stepSequence}:${stepName}`
+    const maxRetries = stepFn.maxRetries ?? defaultTestWorkflowStepMaxRetries
+    const maxAttempts = maxRetries + 1
+
+    let attempt = 1
+
+    for (;;) {
+      run.stepAttempts.set(stepName, (run.stepAttempts.get(stepName) ?? 0) + 1)
+      try {
+        return await ambientStorage.run(
+          { world: this, run, stepMetadata: { attempt, stepId, stepName } },
+          () => stepFn(...args)
+        )
+      } catch (error) {
+        if (attempt >= maxAttempts) throw error
+        attempt += 1
+      }
+    }
+  }
+
+  // Wraps a step function so orchestration code can invoke it exactly the way
+  // the platform invokes `use step` functions: through the retry executor.
+  step<TArgs extends ReadonlyArray<unknown>, TResult>(
+    stepFn: TestWorkflowStepFunction<TArgs, TResult>,
+    stepName?: string
+  ): (...args: TArgs) => Promise<TResult> {
+    return (...args: TArgs) => this.runStep(stepFn, args, stepName)
+  }
+
+  // --- Ambient platform APIs (exposed through `testWorkflowModule`) ---
+
+  static getWorkflowMetadata(): TestWorkflowMetadata {
+    return { workflowRunId: requireAmbient().run.runId }
+  }
+
+  static getStepMetadata(): TestWorkflowStepMetadata {
+    const ambient = requireAmbient()
+
+    if (ambient.stepMetadata === undefined) {
+      throw new Error('getStepMetadata called outside a step context')
+    }
+
+    return ambient.stepMetadata
+  }
+
+  static getWritable<T>(): WritableStream<T> {
+    const ambient = requireAmbient()
+
+    return ambient.world.makeWritable(ambient.run)
+  }
+
+  static createHook<T>(input: { readonly token: string }): TestWorkflowHook<T> {
+    const ambient = requireAmbient()
+
+    return ambient.world.makeHook<T>(ambient.run, input.token)
+  }
+
+  // --- Durable streams ---
+
+  private makeWritable<T>(run: TestWorkflowRunRecord): WritableStream<T> {
+    return new WritableStream<T>({
+      write: chunk => {
+        if (run.streamClosed || run.status === 'cancelled') {
+          run.writeAfterCloseAttempts += 1
+          throw new TestWorkflowStreamConflictError(run.runId)
+        }
+
+        run.chunks.push(chunk)
+        this.notifyChange(run)
+      },
+      close: () => {
+        if (run.streamClosed) {
+          run.streamCloseCount += 1
+          throw new TestWorkflowStreamConflictError(run.runId)
+        }
+
+        run.streamClosed = true
+        run.streamCloseCount += 1
+        this.notifyChange(run)
+      }
+    })
+  }
+
+  private makeHook<T>(run: TestWorkflowRunRecord, token: string): TestWorkflowHook<T> {
+    let resolveHook: (payload: unknown) => void = () => {}
+    let rejectHook: (error: unknown) => void = () => {}
+    const promise = new Promise<T>((resolve, reject) => {
+      // Hook payloads are caller-typed on the platform (`createHook<T>`).
+      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+      resolveHook = payload => resolve(payload as T)
+      rejectHook = reject
+    })
+
+    run.hooks.set(token, { resolve: resolveHook, reject: rejectHook })
+
+    return Object.assign(promise, {
+      [Symbol.dispose]: () => {
+        run.hooks.delete(token)
+      }
+    })
+  }
+
+  getReadable<T>(
+    runId: string,
+    options?: VercelWorkflowReadableOptions
+  ): VercelWorkflowReadableStream<T> {
+    const run = this.requireRun(runId)
+    const requestedStart = options?.startIndex ?? 0
+    let index =
+      requestedStart < 0 ? Math.max(0, run.chunks.length + requestedStart) : requestedStart
+
+    const stream = new ReadableStream<T>({
+      pull: async controller => {
+        while (index >= run.chunks.length && !this.streamEnded(run)) {
+          await this.nextChange(run)
+        }
+
+        if (index < run.chunks.length) {
+          // The platform readable is caller-typed (`WorkflowReadableStream<R = any>`);
+          // the durable log stores opaque chunks, so this coercion mirrors the
+          // platform contract exactly.
+          // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+          controller.enqueue(run.chunks[index] as T)
+          index += 1
+          return
+        }
+
+        controller.close()
+      }
+    })
+
+    return Object.assign(stream, {
+      getTailIndex: () => Promise.resolve(run.chunks.length - 1)
+    })
+  }
+
+  private streamEnded(run: TestWorkflowRunRecord): boolean {
+    return run.streamClosed || run.status === 'cancelled'
+  }
+
+  private notifyChange(run: TestWorkflowRunRecord): void {
+    const listeners = [...run.changeListeners]
+    run.changeListeners.clear()
+    for (const listener of listeners) listener()
+  }
+
+  private nextChange(run: TestWorkflowRunRecord): Promise<void> {
+    return new Promise(resolve => {
+      run.changeListeners.add(resolve)
+    })
+  }
+
+  private requireRun(runId: string): TestWorkflowRunRecord {
+    const run = this.runs.get(runId)
+
+    if (run === undefined) throw new TestWorkflowRunNotFoundError(runId)
+
+    return run
+  }
+
+  // --- SDK adapter for `VercelWorkflows.layerFromSdk` ---
+
+  private sdkRun<TResult>(run: TestWorkflowRunRecord): VercelWorkflowsSdkRun<TResult> {
+    const getReadable = <Chunk>(options?: VercelWorkflowReadableOptions) =>
+      this.getReadable<Chunk>(run.runId, options)
+    const cancel = () => this.cancel(run.runId)
+
+    return {
+      runId: run.runId,
+      getReadable,
+      cancel,
+      get status() {
+        return Promise.resolve(run.status)
+      },
+      get returnValue() {
+        return run.settled.then(() => {
+          // Return values are caller-typed on the platform SDK as well.
+          // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+          if (run.status === 'completed') return run.returnValue as TResult
+
+          throw run.runError ?? new TestWorkflowRunCancelledError(run.runId)
+        })
+      }
+    }
+  }
+
+  readonly sdk: VercelWorkflowsSdkClient = {
+    start: async (workflowFn, args) => {
+      const { runId } = this.start(workflowFn, args)
+
+      return this.sdkRun(this.requireRun(runId))
+    },
+    getRun: <TResult>(runId: string) => this.sdkRun<TResult>(this.requireRun(runId)),
+    resumeHook: (token, payload) => this.resumeHook(token, payload)
+  }
+}
+
+// Factory for `vi.mock('workflow', () => testWorkflowModule)`: the mocked
+// module surface delegates every ambient platform API to the active world's
+// AsyncLocalStorage context, so production code under test runs unmodified.
+export const testWorkflowModule = {
+  getWorkflowMetadata: () => TestWorkflowWorld.getWorkflowMetadata(),
+  getStepMetadata: () => TestWorkflowWorld.getStepMetadata(),
+  getWritable: <T>() => TestWorkflowWorld.getWritable<T>(),
+  createHook: <T>(input: { readonly token: string }) => TestWorkflowWorld.createHook<T>(input)
+}