@notionhq/apps 0.0.1

package/src/workflow.test.ts

@@ -0,0 +1,788 @@
+import { createHash } from "node:crypto";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, beforeEach, describe, expect, expectTypeOf, it, vi, type Mock } from "vitest";
+
+import { ExecutionError } from "./error.js";
+import type { RunMetadata } from "./runtime-metadata.js";
+import { triggers, type NotionPageCreatedEvent } from "./triggers.generated.js";
+import { createWorkflow, type StepContext, type WorkflowContext } from "./workflow.js";
+
+let stdoutSpy: Mock<typeof process.stdout.write>;
+let checkpointDirectory: string | undefined;
+let metadataDirectory: string | undefined;
+
+beforeEach(async () => {
+	stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+	delete process.env.NOTION_WORKFLOW_STEP_DIRECTORY;
+	checkpointDirectory = undefined;
+	metadataDirectory = await mkdtemp(join(tmpdir(), "notion-workflow-metadata-"));
+	await writeRunMetadata();
+});
+
+afterEach(async () => {
+	stdoutSpy.mockRestore();
+	delete process.env.NOTION_WORKFLOW_STEP_DIRECTORY;
+	delete process.env.NOTION_RUN_METADATA_PATH;
+	if (checkpointDirectory) {
+		await rm(checkpointDirectory, { recursive: true, force: true });
+	}
+	if (metadataDirectory) {
+		await rm(metadataDirectory, { recursive: true, force: true });
+	}
+});
+
+const event = { type: "notion.page.created" } as NotionPageCreatedEvent;
+
+async function createWorkflowContext(): Promise<WorkflowContext> {
+	let context: WorkflowContext | undefined;
+	const workflow = createWorkflow({
+		name: "Test workflow",
+		description: "Captures its workflow context",
+		triggers: [triggers.notionPageCreated()],
+		handler: (_event, workflowContext) => {
+			context = workflowContext;
+		},
+	});
+
+	await workflow.handler(event, { concreteOutput: true });
+
+	if (!context) {
+		throw new Error("Workflow context was not created");
+	}
+
+	return context;
+}
+
+function emittedStepEvents(): Array<{
+	event: string;
+	value: Record<string, unknown>;
+}> {
+	return stdoutSpy.mock.calls.map(([output]) => {
+		const match = output
+			.toString()
+			.match(
+				/^\n<__notion_step_(started|success|failure|replayed|completed)__>(.*)<\/__notion_step_\1__>\n$/,
+			);
+
+		if (!match) {
+			throw new Error(`Unexpected step event: ${output.toString()}`);
+		}
+
+		return {
+			event: match[1]!,
+			value: JSON.parse(match[2]!) as Record<string, unknown>,
+		};
+	});
+}
+
+describe("step", () => {
+	it("provides required run metadata in the workflow context", async () => {
+		const context = await createWorkflowContext();
+
+		expect(context).toMatchObject({
+			workspaceId: "workspace-id",
+			workerId: "worker-id",
+			runGroupId: "run-group-id",
+			runId: "run-id",
+			capabilityType: "workflow",
+			attemptNumber: 2,
+		});
+		expectTypeOf(context.workspaceId).toEqualTypeOf<string>();
+		expectTypeOf(context.workerId).toEqualTypeOf<string>();
+		expectTypeOf(context.runGroupId).toEqualTypeOf<string>();
+		expectTypeOf(context.runId).toEqualTypeOf<string>();
+		expectTypeOf(context.capabilityType).toEqualTypeOf<"workflow">();
+		expectTypeOf(context.attemptNumber).toEqualTypeOf<number>();
+	});
+
+	it("runs a synchronous callback and writes success events in order", async () => {
+		const { step } = await createWorkflowContext();
+		let context: StepContext | undefined;
+		const resultPromise = step("Fetch page", (stepContext) => {
+			context = stepContext;
+			return { pageId: "page-1" } as const;
+		});
+
+		expectTypeOf(resultPromise).toEqualTypeOf<Promise<{ readonly pageId: "page-1" }>>();
+		await expect(resultPromise).resolves.toEqual({ pageId: "page-1" });
+
+		expect(context).toBeDefined();
+		const { id } = context!;
+		expect(id).toBe(`run-group-id:${workflowStepKey(["Fetch page"])}`);
+		expect(emittedStepEvents()).toEqual([
+			{
+				event: "started",
+				value: {
+					id,
+					name: "Fetch page",
+					key: workflowStepKey(["Fetch page"]),
+					timestampMs: expect.any(Number),
+					durationMs: expect.any(Number),
+				},
+			},
+			{
+				event: "success",
+				value: {
+					id,
+					name: "Fetch page",
+					key: workflowStepKey(["Fetch page"]),
+					value: { pageId: "page-1" },
+					timestampMs: expect.any(Number),
+					durationMs: expect.any(Number),
+				},
+			},
+			{
+				event: "completed",
+				value: {
+					id,
+					name: "Fetch page",
+					key: workflowStepKey(["Fetch page"]),
+					type: "success",
+					timestampMs: expect.any(Number),
+					durationMs: expect.any(Number),
+				},
+			},
+		]);
+	});
+
+	it("uses stable, distinct ids for steps", async () => {
+		const firstContext = await createWorkflowContext();
+		const firstAttemptIds: string[] = [];
+
+		await firstContext.step("First", ({ id }) => {
+			firstAttemptIds.push(id);
+		});
+		await firstContext.step("Second", ({ id }) => {
+			firstAttemptIds.push(id);
+		});
+
+		await writeRunMetadata({ runId: "retry-run-id", attemptNumber: 3 });
+		const secondContext = await createWorkflowContext();
+		let retryId = "";
+		await secondContext.step("First", ({ id }) => {
+			retryId = id;
+		});
+
+		await writeRunMetadata({
+			runGroupId: "other-run-group-id",
+			runId: "other-run-id",
+			attemptNumber: 1,
+		});
+		const otherRunContext = await createWorkflowContext();
+		let otherRunId = "";
+		await otherRunContext.step("First", ({ id }) => {
+			otherRunId = id;
+		});
+
+		expect(firstAttemptIds).toEqual([
+			`run-group-id:${workflowStepKey(["First"])}`,
+			`run-group-id:${workflowStepKey(["Second"])}`,
+		]);
+		expect(retryId).toBe(firstAttemptIds[0]);
+		expect(otherRunId).toBe(`other-run-group-id:${workflowStepKey(["First"])}`);
+	});
+
+	it("uses an explicit key instead of the display name", async () => {
+		const { step } = await createWorkflowContext();
+		let id = "";
+
+		await step("Fetch the customer page", { key: ["page", "customer"] }, (context) => {
+			id = context.id;
+			return "done";
+		});
+
+		const key = workflowStepKey(["page", "customer"]);
+		expect(key).toHaveLength(43);
+		expect(id).toBe(`run-group-id:${key}`);
+		expect(emittedStepEvents()[0]).toEqual({
+			event: "started",
+			value: {
+				id,
+				name: "Fetch the customer page",
+				key,
+				timestampMs: expect.any(Number),
+				durationMs: expect.any(Number),
+			},
+		});
+	});
+
+	it("wraps an explicit string key in one key segment", async () => {
+		const { step } = await createWorkflowContext();
+		let id = "";
+
+		await step("Fetch the customer page", { key: "customer-page" }, (context) => {
+			id = context.id;
+			return "done";
+		});
+
+		const key = workflowStepKey(["customer-page"]);
+		expect(id).toBe(`run-group-id:${key}`);
+		expect(emittedStepEvents()[0]?.value.key).toBe(key);
+	});
+
+	it("normalizes implicit and explicit undefined results to null", async () => {
+		const { step } = await createWorkflowContext();
+
+		const implicitResult = step("Implicit void", async () => {});
+		expectTypeOf(implicitResult).toEqualTypeOf<Promise<null>>();
+		await expect(implicitResult).resolves.toBeNull();
+
+		const explicitResult = step("Explicit undefined", () => undefined);
+		expectTypeOf(explicitResult).toEqualTypeOf<Promise<null>>();
+		await expect(explicitResult).resolves.toBeNull();
+
+		const successValues = emittedStepEvents()
+			.filter(({ event }) => event === "success")
+			.map(({ value }) => value.value);
+		expect(successValues).toEqual([null, null]);
+	});
+
+	it("timestamps and measures each event when it is emitted", async () => {
+		const { step } = await createWorkflowContext();
+		const nowSpy = vi.spyOn(Date, "now").mockReturnValue(1_721_234_567_890);
+		const performanceNowSpy = vi
+			.spyOn(performance, "now")
+			.mockReturnValueOnce(101)
+			.mockReturnValueOnce(102)
+			.mockReturnValueOnce(103);
+
+		try {
+			await step("Timestamped", () => "done");
+		} finally {
+			nowSpy.mockRestore();
+			performanceNowSpy.mockRestore();
+		}
+
+		expect(emittedStepEvents().map(({ value }) => value.timestampMs)).toEqual([
+			performance.timeOrigin + 101,
+			performance.timeOrigin + 102,
+			performance.timeOrigin + 103,
+		]);
+		expect(emittedStepEvents().map(({ value }) => value.durationMs)).toEqual([0, 1, 2]);
+	});
+
+	it("writes failure events in order and rethrows the original error", async () => {
+		const { step } = await createWorkflowContext();
+		const originalError = new Error("boom");
+		let id = "";
+		const fn = vi.fn((context: StepContext) => {
+			id = context.id;
+			throw originalError;
+		});
+
+		await expect(step("Explode", fn)).rejects.toBe(originalError);
+
+		expect(fn).toHaveBeenCalledOnce();
+		expect(stdoutSpy).toHaveBeenCalledTimes(3);
+		expect(emittedStepEvents()).toEqual([
+			{
+				event: "started",
+				value: {
+					id,
+					name: "Explode",
+					key: workflowStepKey(["Explode"]),
+					timestampMs: expect.any(Number),
+					durationMs: expect.any(Number),
+				},
+			},
+			{
+				event: "failure",
+				value: {
+					id,
+					name: "Explode",
+					key: workflowStepKey(["Explode"]),
+					error: {
+						name: "ExecutionError",
+						message: "Error during app execution: Error: boom",
+						trace: expect.any(String),
+					},
+					timestampMs: expect.any(Number),
+					durationMs: expect.any(Number),
+				},
+			},
+			{
+				event: "completed",
+				value: {
+					id,
+					name: "Explode",
+					key: workflowStepKey(["Explode"]),
+					type: "failure",
+					timestampMs: expect.any(Number),
+					durationMs: expect.any(Number),
+				},
+			},
+		]);
+	});
+
+	it("replays a saved step without calling its function", async () => {
+		const { step } = await createWorkflowContext();
+		const directory = await createCheckpointDirectory();
+		await writeFile(
+			checkpointPath(directory, workflowStepKey(["Fetch page"])),
+			JSON.stringify({
+				version: 0,
+				key: workflowStepKey(["Fetch page"]),
+				value: { pageId: "saved-page" },
+				sourceRunId: "source-run",
+				sourceStepId: "source-step",
+			}),
+		);
+		const fn = vi.fn(() => ({ pageId: "new-page" }));
+
+		await expect(step("Fetch page", fn)).resolves.toEqual({
+			pageId: "saved-page",
+		});
+
+		expect(fn).not.toHaveBeenCalled();
+		const outputs = stdoutSpy.mock.calls.map(([output]) => String(output));
+		expect(outputs).toHaveLength(3);
+		expect(outputs[0]).toContain("<__notion_step_started__>");
+		expect(outputs[0]).toContain(`"key":"${workflowStepKey(["Fetch page"])}"`);
+		expect(outputs[1]).toContain("<__notion_step_replayed__>");
+		expect(outputs[1]).toContain('"sourceRunId":"source-run"');
+		expect(outputs[1]).toContain('"sourceStepId":"source-step"');
+		expect(outputs[2]).toContain("<__notion_step_completed__>");
+		expect(outputs[2]).toContain('"type":"success"');
+	});
+
+	it("replays a normalized void result as null", async () => {
+		const { step } = await createWorkflowContext();
+		const directory = await createCheckpointDirectory();
+		await writeFile(
+			checkpointPath(directory, workflowStepKey(["Side effect"])),
+			JSON.stringify({
+				version: 0,
+				key: workflowStepKey(["Side effect"]),
+				value: null,
+				sourceRunId: "source-run",
+				sourceStepId: "source-step",
+			}),
+		);
+		const fn = vi.fn(() => undefined);
+
+		const result = step("Side effect", fn);
+		expectTypeOf(result).toEqualTypeOf<Promise<null>>();
+		await expect(result).resolves.toBeNull();
+		expect(fn).not.toHaveBeenCalled();
+	});
+
+	it("runs a step when its checkpoint file is missing", async () => {
+		await createCheckpointDirectory();
+		const { step } = await createWorkflowContext();
+		const fn = vi.fn(() => "new-value");
+
+		await expect(step("Run me", fn)).resolves.toBe("new-value");
+
+		expect(fn).toHaveBeenCalledOnce();
+		expect(stdoutSpy.mock.calls.map(([output]) => String(output))).not.toEqual(
+			expect.arrayContaining([expect.stringContaining("__notion_step_replayed__")]),
+		);
+	});
+
+	it("mixes replayed steps with new work", async () => {
+		const directory = await createCheckpointDirectory();
+		await writeFile(
+			checkpointPath(directory, workflowStepKey(["First"])),
+			JSON.stringify({
+				version: 0,
+				key: workflowStepKey(["First"]),
+				value: "saved",
+				sourceRunId: "source-run",
+				sourceStepId: "source-step",
+			}),
+		);
+		const { step } = await createWorkflowContext();
+		const replayedFn = vi.fn(() => "new-first");
+		const newFn = vi.fn(() => "new-second");
+
+		await expect(step("First", replayedFn)).resolves.toBe("saved");
+		await expect(step("Second", newFn)).resolves.toBe("new-second");
+
+		expect(replayedFn).not.toHaveBeenCalled();
+		expect(newFn).toHaveBeenCalledOnce();
+		const outputs = stdoutSpy.mock.calls.map(([output]) => String(output));
+		expect(
+			outputs.filter((output) => output.includes("__notion_step_replayed__")),
+		).toHaveLength(1);
+		expect(outputs).toEqual(
+			expect.arrayContaining([
+				expect.stringContaining(
+					`"name":"Second","key":"${workflowStepKey(["Second"])}","value":"new-second"`,
+				),
+			]),
+		);
+	});
+
+	it.each([
+		{
+			name: "invalid JSON",
+			contents: "{",
+		},
+		{
+			name: "an invalid shape",
+			contents: "[]",
+		},
+		{
+			name: "wrong version",
+			contents: JSON.stringify({
+				version: 1,
+				key: workflowStepKey(["Do not rerun"]),
+				value: "saved",
+				sourceRunId: "source-run",
+				sourceStepId: "source-step",
+			}),
+		},
+		{
+			name: "wrong key",
+			contents: JSON.stringify({
+				version: 0,
+				key: "other",
+				value: "saved",
+				sourceRunId: "source-run",
+				sourceStepId: "source-step",
+			}),
+		},
+		{
+			name: "a missing value",
+			contents: JSON.stringify({
+				version: 0,
+				key: workflowStepKey(["Do not rerun"]),
+				sourceRunId: "source-run",
+				sourceStepId: "source-step",
+			}),
+		},
+		{
+			name: "missing source ids",
+			contents: JSON.stringify({
+				version: 0,
+				key: workflowStepKey(["Do not rerun"]),
+				value: "saved",
+			}),
+		},
+	])("fails instead of rerunning a step for $name", async ({ contents }) => {
+		const directory = await createCheckpointDirectory();
+		await writeFile(checkpointPath(directory, workflowStepKey(["Do not rerun"])), contents);
+		const { step } = await createWorkflowContext();
+		const fn = vi.fn(() => "new-value");
+
+		await expect(step("Do not rerun", fn)).rejects.toBeInstanceOf(Error);
+
+		expect(fn).not.toHaveBeenCalled();
+		expect(stdoutSpy.mock.calls.map(([output]) => String(output))).toEqual(
+			expect.arrayContaining([
+				expect.stringContaining("<__notion_step_failure__>"),
+				expect.stringContaining('"type":"failure"'),
+			]),
+		);
+	});
+
+	it("fails instead of rerunning a step when its checkpoint cannot be read", async () => {
+		const directory = await createCheckpointDirectory();
+		await mkdir(checkpointPath(directory, workflowStepKey(["Do not rerun"])));
+		const { step } = await createWorkflowContext();
+		const fn = vi.fn(() => "new-value");
+
+		await expect(step("Do not rerun", fn)).rejects.toBeInstanceOf(Error);
+
+		expect(fn).not.toHaveBeenCalled();
+		expect(stdoutSpy.mock.calls.map(([output]) => String(output))).toEqual(
+			expect.arrayContaining([
+				expect.stringContaining("<__notion_step_failure__>"),
+				expect.stringContaining('"type":"failure"'),
+			]),
+		);
+	});
+
+	it("uses names as keys for overlapping steps regardless of completion order", async () => {
+		const { step } = await createWorkflowContext();
+		let finishFirst: (() => void) | undefined;
+		const result = Promise.all([
+			step(
+				"First",
+				() =>
+					new Promise<string>((resolve) => {
+						finishFirst = () => resolve("first");
+					}),
+			),
+			step("Second", () => "second"),
+		]);
+
+		await Promise.resolve();
+		finishFirst?.();
+		await expect(result).resolves.toEqual(["first", "second"]);
+
+		const started = stdoutSpy.mock.calls
+			.map(([output]) => String(output))
+			.filter((output) => output.includes("<__notion_step_started__>"));
+		expect(started[0]).toContain(`"name":"First","key":"${workflowStepKey(["First"])}"`);
+		expect(started[1]).toContain(`"name":"Second","key":"${workflowStepKey(["Second"])}"`);
+	});
+
+	it("rejects duplicate default and explicit keys", async () => {
+		const { step } = await createWorkflowContext();
+		const duplicateDefaultFn = vi.fn(() => "duplicate");
+		const duplicateExplicitFn = vi.fn(() => "duplicate");
+
+		await expect(step("Duplicate", () => "first")).resolves.toBe("first");
+		await expect(step("Duplicate", duplicateDefaultFn)).rejects.toThrow(
+			'Workflow step "Duplicate" has the same key as "Duplicate"',
+		);
+		await expect(
+			step("Different name", { key: "Duplicate" }, duplicateExplicitFn),
+		).rejects.toThrow('Workflow step "Different name" has the same key as "Duplicate"');
+
+		expect(duplicateDefaultFn).not.toHaveBeenCalled();
+		expect(duplicateExplicitFn).not.toHaveBeenCalled();
+	});
+
+	it("rejects empty explicit keys", async () => {
+		const { step } = await createWorkflowContext();
+		const fn = vi.fn(() => "value");
+
+		await expect(step("Display name", { key: [] }, fn)).rejects.toThrow(
+			"Workflow step keys must contain at least one segment.",
+		);
+
+		expect(fn).not.toHaveBeenCalled();
+		expect(stdoutSpy).not.toHaveBeenCalled();
+	});
+
+	it("rejects empty explicit key segments", async () => {
+		const { step } = await createWorkflowContext();
+		const fn = vi.fn(() => "value");
+
+		await expect(step("Display name", { key: [""] }, fn)).rejects.toThrow(
+			"Workflow step key segments must not be empty.",
+		);
+
+		expect(fn).not.toHaveBeenCalled();
+		expect(stdoutSpy).not.toHaveBeenCalled();
+	});
+
+	it("leaves step names unchanged for runtime validation", async () => {
+		const { step } = await createWorkflowContext();
+		const name = "Résumé\u0000\t日本語\n👨‍👩‍👧‍👦\u200b";
+
+		await expect(step(name, { key: "raw-name" }, () => "value")).resolves.toBe("value");
+
+		expect(emittedStepEvents()[0]?.value).toEqual(
+			expect.objectContaining({
+				name,
+				key: workflowStepKey(["raw-name"]),
+			}),
+		);
+	});
+
+	it("allows steps to invoke other uniquely named steps", async () => {
+		const { step } = await createWorkflowContext();
+
+		await expect(
+			step("Parent", async () => {
+				return step("Child", () => "child-value");
+			}),
+		).resolves.toBe("child-value");
+
+		expect(emittedStepEvents().map(({ event, value }) => [event, value.key])).toEqual([
+			["started", workflowStepKey(["Parent"])],
+			["started", workflowStepKey(["Child"])],
+			["success", workflowStepKey(["Child"])],
+			["completed", workflowStepKey(["Child"])],
+			["success", workflowStepKey(["Parent"])],
+			["completed", workflowStepKey(["Parent"])],
+		]);
+	});
+
+	it("keeps nested and later step keys stable when a parent is replayed", async () => {
+		const directory = await createCheckpointDirectory();
+		for (const [key, value] of [
+			["Parent", "saved-parent"],
+			["Child", "saved-child"],
+			["Sibling", "saved-sibling"],
+		] as const) {
+			const wireKey = workflowStepKey([key]);
+			await writeFile(
+				checkpointPath(directory, wireKey),
+				JSON.stringify({
+					version: 0,
+					key: wireKey,
+					value,
+					sourceRunId: "source-run",
+					sourceStepId: `source-${key.toLowerCase()}`,
+				}),
+			);
+		}
+		const { step } = await createWorkflowContext();
+		const childFn = vi.fn(() => "new-child");
+		const siblingFn = vi.fn(() => "new-sibling");
+
+		await expect(
+			step("Parent", async () => {
+				await step("Child", childFn);
+				return "new-parent";
+			}),
+		).resolves.toBe("saved-parent");
+		await expect(step("Sibling", siblingFn)).resolves.toBe("saved-sibling");
+
+		expect(childFn).not.toHaveBeenCalled();
+		expect(siblingFn).not.toHaveBeenCalled();
+		expect(
+			emittedStepEvents()
+				.filter(({ event }) => event === "started")
+				.map(({ value }) => value.key),
+		).toEqual([workflowStepKey(["Parent"]), workflowStepKey(["Sibling"])]);
+	});
+
+	it("resets duplicate key tracking for each workflow call", async () => {
+		const keys: string[] = [];
+		const workflow = createWorkflow({
+			name: "Reuse step key",
+			description: "Checks that a key can be reused in a new invocation",
+			triggers: [triggers.notionPageCreated()],
+			handler: async (_event, context) => {
+				await context.step("First", () => undefined);
+				const started = stdoutSpy.mock.calls
+					.map(([output]) => String(output))
+					.findLast((output) => output.includes("<__notion_step_started__>"));
+				const match = started?.match(/"key":"([^"]+)"/);
+				if (match?.[1]) {
+					keys.push(match[1]);
+				}
+			},
+		});
+
+		await workflow.handler(event, { concreteOutput: true });
+		await workflow.handler(event, { concreteOutput: true });
+
+		expect(keys).toEqual([workflowStepKey(["First"]), workflowStepKey(["First"])]);
+	});
+
+	it("writes step events under concreteOutput", async () => {
+		const workflow = createWorkflow({
+			name: "Log Pages",
+			description: "Logs created pages",
+			triggers: [triggers.notionPageCreated()],
+			handler: async (_event, context) => {
+				await context.step("Always visible", () => "done");
+			},
+		});
+
+		await workflow.handler(event, { concreteOutput: true });
+
+		expect(stdoutSpy).toHaveBeenCalledTimes(3);
+		expect(stdoutSpy.mock.calls[0]?.[0]).toEqual(
+			expect.stringContaining("<__notion_step_started__>"),
+		);
+		expect(stdoutSpy.mock.calls[1]?.[0]).toEqual(
+			expect.stringContaining("<__notion_step_success__>"),
+		);
+		expect(stdoutSpy.mock.calls[2]?.[0]).toEqual(expect.stringContaining('"type":"success"'));
+	});
+});
+
+async function createCheckpointDirectory(): Promise<string> {
+	checkpointDirectory = await mkdtemp(join(tmpdir(), "apps-step-checkpoints-"));
+	process.env.NOTION_WORKFLOW_STEP_DIRECTORY = checkpointDirectory;
+	return checkpointDirectory;
+}
+
+function checkpointPath(directory: string, key: string): string {
+	const keyHash = createHash("sha256").update(key).digest("hex");
+	return join(directory, `${keyHash}.json`);
+}
+
+function workflowStepKey(segments: readonly string[]): string {
+	return createHash("sha256")
+		.update(JSON.stringify(["notion-workflow-step-key", 1, ...segments]))
+		.digest("base64url");
+}
+
+async function writeRunMetadata(overrides: Partial<RunMetadata> = {}): Promise<void> {
+	if (!metadataDirectory) {
+		throw new Error("Metadata directory was not created");
+	}
+
+	const metadataPath = join(metadataDirectory, "metadata.json");
+	await writeFile(
+		metadataPath,
+		JSON.stringify({
+			workspaceId: "workspace-id",
+			workerId: "worker-id",
+			runGroupId: "run-group-id",
+			runId: "run-id",
+			capabilityType: "workflow",
+			attemptNumber: 2,
+			...overrides,
+		} satisfies RunMetadata),
+	);
+	process.env.NOTION_RUN_METADATA_PATH = metadataPath;
+}
+
+describe("createWorkflow", () => {
+	it("is tagged and exposes triggers in config", () => {
+		const workflow = createWorkflow({
+			name: "Log Pages",
+			description: "Logs created pages",
+			triggers: [triggers.notionPageCreated()],
+			handler: () => {},
+		});
+
+		expect(workflow._tag).toBe("workflow");
+		expect(workflow.config).toEqual({
+			name: "Log Pages",
+			description: "Logs created pages",
+			triggers: [{ type: "notion.page.created" }],
+		});
+	});
+
+	it("writes a success envelope after the handler runs", async () => {
+		const handler = vi.fn();
+		const workflow = createWorkflow({
+			name: "Log Pages",
+			description: "Logs created pages",
+			triggers: [triggers.notionPageCreated()],
+			handler,
+		});
+
+		await workflow.handler(event);
+
+		expect(handler).toHaveBeenCalledWith(event, expect.anything());
+		expect(stdoutSpy).toHaveBeenCalledWith(
+			`\n<__notion_output__>{"_tag":"success","value":{"status":"success"}}</__notion_output__>\n`,
+		);
+	});
+
+	it("returns the status without an envelope under concreteOutput", async () => {
+		const workflow = createWorkflow({
+			name: "Log Pages",
+			description: "Logs created pages",
+			triggers: [triggers.notionPageCreated()],
+			handler: () => {},
+		});
+
+		await expect(workflow.handler(event, { concreteOutput: true })).resolves.toEqual({
+			status: "success",
+		});
+		expect(stdoutSpy).not.toHaveBeenCalled();
+	});
+
+	it("writes an error envelope and throws ExecutionError on failure", async () => {
+		const workflow = createWorkflow({
+			name: "Log Pages",
+			description: "Logs created pages",
+			triggers: [triggers.notionPageCreated()],
+			handler: () => {
+				throw new Error("boom");
+			},
+		});
+
+		await expect(workflow.handler(event)).rejects.toBeInstanceOf(ExecutionError);
+		expect(stdoutSpy).toHaveBeenCalledWith(
+			expect.stringContaining(
+				`<__notion_output__>{"_tag":"error","error":{"name":"ExecutionError","message":"Error during app execution: Error: boom"`,
+			),
+		);
+	});
+});