@notionhq/apps 0.0.40 → 0.0.42

package/skills/workflow/SKILL.md

@@ -99,6 +99,52 @@ await context.step("Process page", { key: ["process-page", page.id] }, async ({
 
 Keys must be stable across retries and unique within one workflow run.
 
+Configure a workflow deadline and retry policy only when the platform defaults do
+not fit the workflow:
+
+```ts
+export default workflow({
+	name: "Charge customer",
+	description: "Charges a customer when an invoice is created",
+	triggers: [events.notionPageCreated()],
+	deadline: { afterMs: 7 * 24 * 60 * 60 * 1000 },
+	retry: {
+		maxAttempts: 3,
+		initialDelayMs: 5_000,
+		maxDelayMs: 5 * 60 * 1000,
+		backoffMultiplier: 2,
+	},
+	handler: async (_event, context) => {
+		await context.step(
+			"Charge customer",
+			{ timeoutMs: 30_000, retry: { maxAttempts: 2 } },
+			chargeCustomer,
+		);
+	},
+});
+```
+
+The workflow `retry` policy is the default for every step; a step's `retry`
+replaces it rather than stacking. The run itself is retried only for failures
+outside a step. A step that fails after using its retries fails the run.
+
+`maxAttempts` includes the initial attempt and is at most 4. Without any policy,
+steps make 3 attempts with jittered backoff starting at 1 second, doubling, and
+capped at 5 minutes. A step retries ordinary errors and `RetryableError`, but
+stops immediately for `FatalError`. Set `retryOn` to an error class, a predicate,
+or an array of them to retry only matching errors, for example
+`retryOn: TimeoutError` or `retryOn: [TimeoutError, RateLimitError]`. Pass
+`retryAfterMs` to `RetryableError` when the failing service provides an explicit
+delay. Workflow deadlines include retry delays and are at most 7 days, and step
+timeouts apply to one callback attempt.
+
+Step retries wait inside one workflow invocation, which runs for at most 5
+minutes. The longest possible retry delays plus `timeoutMs` for every attempt
+must fit in 5 minutes, for step policies and for the workflow `retry` policy
+that steps inherit. Earlier work in the invocation counts against the same 5
+minutes; a retry that no longer fits is left to a run retry. Use
+`context.wait.until()` for longer waits.
+
 An external effect can succeed before its step result is saved. Pass the
 callback `id` as an idempotency key when supported; otherwise use a stable
 external ID, upsert, or duplicate check.

package/src/cli/build.test.ts

@@ -456,6 +456,43 @@ describe("buildApp", () => {
 		});
 	});
 
+	it("emits APP.md as a private page with stable identity and resource references", async () => {
+		const root = await fs.promises.mkdtemp(path.join(FIXTURES, "app-md-"));
+		try {
+			await fs.promises.cp(
+				path.join(FIXTURES, "notion-as-code", "src"),
+				path.join(root, "src"),
+				{
+					recursive: true,
+				},
+			);
+			const markdown =
+				'# App guide\n\nSee <mention-page url="{{github-app-private-page}}">Home</mention-page>.\n';
+			await fs.promises.writeFile(path.join(root, "APP.md"), markdown);
+			await buildApp(root);
+			const provisioningPath = path.join(root, "dist", "provisioning.json");
+			const provisioning = JSON.parse(await fs.promises.readFile(provisioningPath, "utf8"));
+			expect(provisioning.intents.at(-1)).toEqual({
+				type: "page",
+				resourceId: "__notion_apps_app_md__",
+				parent: { type: "resourceId", resourceId: "__notion_apps_workspace__" },
+				properties: { title: [["APP.md"]] },
+				content: markdown,
+			});
+
+			await fs.promises.rm(path.join(root, "APP.md"));
+			await buildApp(root);
+			const withoutAppPage = JSON.parse(await fs.promises.readFile(provisioningPath, "utf8"));
+			expect(withoutAppPage.intents).not.toEqual(
+				expect.arrayContaining([
+					expect.objectContaining({ resourceId: "__notion_apps_app_md__" }),
+				]),
+			);
+		} finally {
+			await fs.promises.rm(root, { recursive: true, force: true });
+		}
+	});
+
 	it("removes provisioning when a rebuild no longer declares Notion resources", async () => {
 		const root = await fs.promises.mkdtemp(path.join(FIXTURES, "provisioning-rebuild-"));
 		try {

package/src/cli/build.ts

@@ -4,6 +4,7 @@ import * as path from "node:path";
 import { rolldown } from "rolldown";
 
 import type { AppManifest } from "../manifest.js";
+import { APPS_WORKSPACE_RESOURCE_ID, type PageIntent } from "../notion-as-code/intents.js";
 import {
 	createProvisioningArtifact,
 	type RecordedProvisioning,
@@ -13,6 +14,8 @@ import { generateEntry, generateMetadataEntry, generateBlocksEntry } from "./cod
 import { discoverCapabilities, type DiscoveredCapability } from "./discover.js";
 import { extractManifest, extractProvisioning, extractBlockConfigs } from "./emit-manifest.js";
 
+const APP_MD_RESOURCE_ID = "__notion_apps_app_md__";
+
 export type BuildResult = {
 	manifest: AppManifest;
 	bundlePath: string;
@@ -75,15 +78,40 @@ async function emitProvisioningArtifact(
 	entityProvisioning: RecordedProvisioning,
 ): Promise<void> {
 	const provisioningPath = path.join(projectRoot, "dist", "provisioning.json");
-	if (entityProvisioning.intents.length === 0) {
+	const appPage = await readAppPage(projectRoot);
+	if (entityProvisioning.intents.length === 0 && !appPage) {
 		await fs.promises.rm(provisioningPath, { force: true });
 		return;
 	}
 
-	const artifact = createProvisioningArtifact(entityProvisioning.intents);
+	const artifact = createProvisioningArtifact([
+		...entityProvisioning.intents,
+		...(appPage ? [appPage] : []),
+	]);
 	await fs.promises.writeFile(provisioningPath, `${JSON.stringify(artifact, null, "\t")}\n`);
 }
 
+async function readAppPage(
+	projectRoot: string,
+): Promise<({ type: "page" } & PageIntent) | undefined> {
+	let content: string;
+	try {
+		content = await fs.promises.readFile(path.join(projectRoot, "APP.md"), "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+			return undefined;
+		}
+		throw error;
+	}
+	return {
+		type: "page",
+		resourceId: APP_MD_RESOURCE_ID,
+		parent: { type: "resourceId", resourceId: APPS_WORKSPACE_RESOURCE_ID },
+		properties: { title: [["APP.md"]] },
+		content,
+	};
+}
+
 /** Bundle capabilities separately to record their Notion-as-Code declarations without shipping them. */
 async function buildMetadata(
 	projectRoot: string,

package/src/error.ts

@@ -11,6 +11,31 @@ export class ExecutionError extends Error {
 	}
 }
 
+/** Explicitly permit another workflow or step attempt. */
+export class RetryableError extends Error {
+	readonly retryAfterMs: number | undefined;
+
+	constructor(message: string, options?: { retryAfterMs?: number }) {
+		super(message);
+		this.name = "RetryableError";
+		if (
+			options?.retryAfterMs !== undefined &&
+			(!Number.isFinite(options.retryAfterMs) || options.retryAfterMs < 0)
+		) {
+			throw new Error("RetryableError retryAfterMs must be zero or greater.");
+		}
+		this.retryAfterMs = options?.retryAfterMs;
+	}
+}
+
+/** Skip remaining workflow or step attempts. */
+export class FatalError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "FatalError";
+	}
+}
+
 /** Tell the platform that an external service asked the sync to slow down. */
 export class RateLimitError extends ExecutionError {
 	readonly retryAfter: number | undefined;

package/src/workflow.test.ts

@@ -6,7 +6,7 @@ import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, expectTypeOf, it, vi, type Mock } from "vitest";
 
 import { j } from "./schema-builder.js";
-import { ExecutionError } from "./error.js";
+import { ExecutionError, FatalError, RateLimitError, RetryableError } from "./error.js";
 import type { RunMetadata } from "./runtime-metadata.js";
 import { events, type NotionPageCreatedEvent, type WebhookEvent } from "./events.generated.js";
 import { customAgent } from "./notion-as-code/custom-agent.js";
@@ -21,6 +21,7 @@ import {
 	type WebhookVerifyHandler,
 	type WorkflowContext,
 	type WorkflowInputDate,
+	type WorkflowRetryPolicy,
 	type WorkflowWaitDuration,
 } from "./workflow.js";
 
@@ -124,12 +125,15 @@ describe("manual workflow triggers", () => {
 	});
 });
 
-async function createWorkflowContext(): Promise<WorkflowContext<Record<never, never>>> {
+async function createWorkflowContext(
+	retry?: WorkflowRetryPolicy,
+): Promise<WorkflowContext<Record<never, never>>> {
 	let context: WorkflowContext<Record<never, never>> | undefined;
 	const definition = workflow({
 		name: "Test workflow",
 		description: "Captures its workflow context",
 		triggers: [events.notionPageCreated()],
+		...(retry === undefined ? {} : { retry }),
 		handler: (_event, workflowContext) => {
 			context = workflowContext;
 		},
@@ -249,6 +253,41 @@ describe("step", () => {
 		expect(fetchMock).not.toHaveBeenCalled();
 	});
 
+	it("isolates buffered state between step retry attempts", async () => {
+		process.env.NOTION_API_BASE_URL = "https://api.example.com";
+		process.env.NOTION_API_TOKEN = "workflow-token";
+		const fetchMock = vi.fn<typeof fetch>().mockImplementation(async (_input, init) => {
+			const body = JSON.parse(String(init?.body)) as { operation: string };
+			return new Response(
+				JSON.stringify(body.operation === "get" ? { exists: false } : { success: true }),
+				{ status: 200, headers: { "content-type": "application/json" } },
+			);
+		});
+		vi.stubGlobal("fetch", fetchMock);
+		const context = await createWorkflowContext();
+		const seen: unknown[] = [];
+		let attempts = 0;
+
+		await context.step("Retry with state", { retry: { maxAttempts: 2 } }, async ({ state }) => {
+			attempts += 1;
+			seen.push(await state.get("failed-attempt"));
+			if (attempts === 1) {
+				state.set("failed-attempt", true);
+				throw new RetryableError("try again");
+			}
+			state.set("succeeded", true);
+		});
+
+		expect(seen).toEqual([undefined, undefined]);
+		const commits = fetchMock.mock.calls
+			.map(([, init]) => String(init?.body))
+			.filter((body) => body.includes('"operation":"commit"'));
+		expect(commits).toHaveLength(1);
+		expect(commits[0]).toContain(
+			'"mutations":[{"operation":"set","key":"succeeded","value":true}]',
+		);
+	});
+
 	it("reads buffered state before the step commits", async () => {
 		process.env.NOTION_API_BASE_URL = "https://api.example.com";
 		process.env.NOTION_API_TOKEN = "workflow-token";
@@ -522,7 +561,9 @@ describe("step", () => {
 			throw originalError;
 		});
 
-		await expect(step("Explode", fn)).rejects.toBe(originalError);
+		await expect(step("Explode", { retry: { maxAttempts: 1 } }, fn)).rejects.toBe(
+			originalError,
+		);
 
 		expect(fn).toHaveBeenCalledOnce();
 		expect(stdoutSpy).toHaveBeenCalledTimes(3);
@@ -908,6 +949,244 @@ describe("step", () => {
 		expect(keys).toEqual([workflowStepKey(["First"]), workflowStepKey(["First"])]);
 	});
 
+	it("retries a failed callback using the step policy", async () => {
+		const { step } = await createWorkflowContext();
+		const callback = vi
+			.fn<() => string>()
+			.mockRejectedValueOnce(new Error("temporary"))
+			.mockReturnValue("done");
+
+		await expect(
+			step("Retry request", { retry: { maxAttempts: 2, initialDelayMs: 0 } }, callback),
+		).resolves.toBe("done");
+		expect(callback).toHaveBeenCalledTimes(2);
+	});
+
+	it("uses the workflow retry policy for steps without their own", async () => {
+		const { step } = await createWorkflowContext({ maxAttempts: 2, initialDelayMs: 0 });
+		const callback = vi.fn<() => string>().mockRejectedValue(new Error("down"));
+
+		await expect(step("Inherit policy", callback)).rejects.toThrow("down");
+		expect(callback).toHaveBeenCalledTimes(2);
+	});
+
+	it("replaces the workflow retry policy with the step policy", async () => {
+		const { step } = await createWorkflowContext({ maxAttempts: 3, initialDelayMs: 0 });
+		const callback = vi.fn<() => string>().mockRejectedValue(new Error("down"));
+
+		await expect(
+			step("Override policy", { retry: { maxAttempts: 1 } }, callback),
+		).rejects.toThrow("down");
+		expect(callback).toHaveBeenCalledOnce();
+	});
+
+	it("makes three attempts with backoff when no policy is configured", async () => {
+		vi.useFakeTimers();
+		try {
+			const { step } = await createWorkflowContext();
+			const callback = vi.fn<() => string>().mockRejectedValue(new Error("down"));
+
+			const result = step("Default policy", callback);
+			const assertion = expect(result).rejects.toThrow("down");
+			await vi.advanceTimersByTimeAsync(3_000);
+			await assertion;
+			expect(callback).toHaveBeenCalledTimes(3);
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+
+	it("retries only errors matched by retryOn", async () => {
+		class TransientError extends Error {}
+		const { step } = await createWorkflowContext({
+			maxAttempts: 3,
+			initialDelayMs: 0,
+			retryOn: [TransientError, (error) => error instanceof Error && error.message === "429"],
+		});
+
+		const transient = vi.fn<() => string>().mockRejectedValue(new TransientError("blip"));
+		await expect(step("Class match", transient)).rejects.toThrow("blip");
+		expect(transient).toHaveBeenCalledTimes(3);
+
+		const predicate = vi.fn<() => string>().mockRejectedValue(new Error("429"));
+		await expect(step("Predicate match", predicate)).rejects.toThrow("429");
+		expect(predicate).toHaveBeenCalledTimes(3);
+
+		const other = vi.fn<() => string>().mockRejectedValue(new TypeError("bug"));
+		await expect(step("No match", other)).rejects.toThrow("bug");
+		expect(other).toHaveBeenCalledOnce();
+
+		const explicit = vi.fn<() => string>().mockRejectedValue(new RetryableError("again"));
+		await expect(step("Explicit retryable", explicit)).rejects.toThrow("again");
+		expect(explicit).toHaveBeenCalledTimes(3);
+	});
+
+	it("accepts a single retryOn matcher", async () => {
+		class TransientError extends Error {}
+		const { step } = await createWorkflowContext({
+			maxAttempts: 2,
+			initialDelayMs: 0,
+			retryOn: TransientError,
+		});
+
+		const transient = vi.fn<() => string>().mockRejectedValue(new TransientError("blip"));
+		await expect(step("Class match", transient)).rejects.toThrow("blip");
+		expect(transient).toHaveBeenCalledTimes(2);
+
+		const other = vi.fn<() => string>().mockRejectedValue(new TypeError("bug"));
+		await expect(step("No match", other)).rejects.toThrow("bug");
+		expect(other).toHaveBeenCalledOnce();
+	});
+
+	it("never retries a FatalError matched by retryOn", async () => {
+		const { step } = await createWorkflowContext({
+			maxAttempts: 3,
+			initialDelayMs: 0,
+			retryOn: [Error],
+		});
+		const callback = vi.fn<() => string>().mockRejectedValue(new FatalError("stop"));
+
+		await expect(step("Fatal", callback)).rejects.toThrow("stop");
+		expect(callback).toHaveBeenCalledOnce();
+	});
+
+	it("rejects step retry policies that cannot fit in one invocation", async () => {
+		const { step } = await createWorkflowContext();
+		const callback = vi.fn(() => "done");
+
+		await expect(
+			step("Slow retries", { retry: { maxAttempts: 3, initialDelayMs: 200_000 } }, callback),
+		).rejects.toThrow(
+			'Workflow step "Slow retries" can spend up to 500000ms on retry delays and timeouts, which exceeds the 300000ms limit',
+		);
+		await expect(
+			step("Long timeout", { timeoutMs: 120_000, retry: { maxAttempts: 3 } }, callback),
+		).rejects.toThrow('Workflow step "Long timeout" can spend up to 363000ms');
+		expect(callback).not.toHaveBeenCalled();
+		expect(() =>
+			workflow({
+				name: "Slow workflow",
+				description: "Its retry policy is the default for every step",
+				triggers: [events.notionPageCreated()],
+				retry: { maxAttempts: 3, initialDelayMs: 200_000 },
+				handler: () => {},
+			}),
+		).toThrow("Workflow retry policy can spend up to 500000ms");
+	});
+
+	it("leaves a retry that no longer fits in the invocation to the run", async () => {
+		const definition = workflow({
+			name: "Deferred retry",
+			description: "Hands a long explicit delay to the platform",
+			triggers: [events.notionPageCreated()],
+			handler: async (_event, context) => {
+				await context.step("Wait for service", () => {
+					throw new RetryableError("busy", { retryAfterMs: 10 * 60 * 1000 });
+				});
+			},
+		});
+
+		await expect(definition.handler(event)).rejects.toBeInstanceOf(ExecutionError);
+		expect(stdoutSpy).toHaveBeenLastCalledWith(
+			expect.stringContaining(
+				`<__notion_output__>{"_tag":"error","error":{"_tag":"retryable","name":"RetryableError","message":"busy"`,
+			),
+		);
+		expect(stdoutSpy).toHaveBeenLastCalledWith(
+			expect.stringContaining(`"retryAfterMs":600000`),
+		);
+	});
+
+	it("counts earlier work in the invocation against the step retry budget", async () => {
+		vi.useFakeTimers();
+		try {
+			const callback = vi.fn(() => {
+				throw new RetryableError("busy", { retryAfterMs: 60_000 });
+			});
+			const definition = workflow({
+				name: "Late retry",
+				description: "Fails a step near the end of the invocation",
+				triggers: [events.notionPageCreated()],
+				handler: async (_event, context) => {
+					await new Promise((resolve) => setTimeout(resolve, 4.5 * 60 * 1000));
+					await context.step("Call service", callback);
+				},
+			});
+
+			const result = expect(definition.handler(event)).rejects.toBeInstanceOf(ExecutionError);
+			await vi.runAllTimersAsync();
+			await result;
+			expect(callback).toHaveBeenCalledOnce();
+			expect(stdoutSpy).toHaveBeenLastCalledWith(
+				expect.stringContaining(`"retryAfterMs":60000`),
+			);
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+
+	it("writes a rate limit envelope for a RateLimitError", async () => {
+		const definition = workflow({
+			name: "Rate limited",
+			description: "Reports the service's retry delay",
+			triggers: [events.notionPageCreated()],
+			handler: () => {
+				throw new RateLimitError({ retryAfter: 30 });
+			},
+		});
+
+		await expect(definition.handler(event)).rejects.toBeInstanceOf(ExecutionError);
+		expect(stdoutSpy).toHaveBeenLastCalledWith(
+			expect.stringContaining(
+				`{"_tag":"error","error":{"_tag":"rate_limit","name":"RateLimitError"`,
+			),
+		);
+		expect(stdoutSpy).toHaveBeenLastCalledWith(expect.stringContaining(`"retryAfter":30`));
+	});
+
+	it("waits for the delay requested by a RateLimitError", async () => {
+		vi.useFakeTimers();
+		try {
+			const { step } = await createWorkflowContext();
+			const callback = vi
+				.fn<() => string>()
+				.mockRejectedValueOnce(new RateLimitError({ retryAfter: 30 }))
+				.mockReturnValue("done");
+
+			const result = step("Rate limited", { retry: { maxAttempts: 2 } }, callback);
+			await vi.advanceTimersByTimeAsync(29_000);
+			expect(callback).toHaveBeenCalledOnce();
+			await vi.advanceTimersByTimeAsync(1_000);
+			await expect(result).resolves.toBe("done");
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+
+	it("does not retry a FatalError", async () => {
+		const { step } = await createWorkflowContext();
+		const error = new FatalError("invalid input");
+		const callback = vi.fn(() => {
+			throw error;
+		});
+
+		await expect(step("Validate input", { retry: { maxAttempts: 3 } }, callback)).rejects.toBe(
+			error,
+		);
+		expect(callback).toHaveBeenCalledOnce();
+	});
+
+	it("times out a step callback", async () => {
+		const { step } = await createWorkflowContext();
+
+		await expect(
+			step("Wait forever", { timeoutMs: 1 }, () => new Promise(() => {})),
+		).rejects.toMatchObject({
+			name: "StepTimeoutError",
+			message: "Workflow step timed out after 1ms.",
+		});
+	});
+
 	it("writes step events under concreteOutput", async () => {
 		const definition = workflow({
 			name: "Log Pages",
@@ -1350,6 +1629,74 @@ describe("workflow", () => {
 		});
 	});
 
+	it("exposes deadline and retry configuration", () => {
+		const deadline = { afterMs: 60_000 };
+		const retry = {
+			maxAttempts: 3,
+			initialDelayMs: 1_000,
+			maxDelayMs: 30_000,
+			backoffMultiplier: 2,
+		};
+		const definition = workflow({
+			name: "Reliable workflow",
+			description: "Configures failure handling",
+			triggers: [events.notionPageCreated()],
+			deadline,
+			retry,
+			handler: () => {},
+		});
+
+		expect(definition.config.deadline).toEqual(deadline);
+		expect(definition.config.retry).toEqual(retry);
+		expect(
+			workflow({
+				name: "Classified workflow",
+				description: "Keeps error matchers in the SDK",
+				triggers: [events.notionPageCreated()],
+				retry: { ...retry, retryOn: [TypeError] },
+				handler: () => {},
+			}).config.retry,
+		).toEqual(retry);
+		expect(definition.config.deadline).not.toBe(deadline);
+		expect(definition.config.retry).not.toBe(retry);
+	});
+
+	it("rejects invalid workflow reliability configuration", () => {
+		expect(() =>
+			workflow({
+				name: "Invalid workflow",
+				description: "Has an invalid retry budget",
+				triggers: [events.notionPageCreated()],
+				deadline: { afterMs: 0 },
+				retry: { maxAttempts: 0 },
+				handler: () => {},
+			}),
+		).toThrow("Workflow deadline afterMs must be greater than zero.");
+	});
+
+	it("rejects reliability configuration beyond platform limits", () => {
+		const define = (config: { deadline?: { afterMs: number }; retry?: WorkflowRetryPolicy }) =>
+			workflow({
+				name: "Limited workflow",
+				description: "Exceeds platform limits",
+				triggers: [events.notionPageCreated()],
+				...config,
+				handler: () => {},
+			});
+
+		expect(() => define({ retry: { maxAttempts: 4 } })).toThrow(
+			"Workflow retry policy maxAttempts must be an integer between 1 and 3.",
+		);
+		expect(() => define({ deadline: { afterMs: 8 * 24 * 60 * 60 * 1000 } })).toThrow(
+			"Workflow deadline afterMs must be at most 604800000.",
+		);
+		expect(() =>
+			define({ retry: { maxAttempts: 2, retryOn: ["TypeError"] as unknown as [] } }),
+		).toThrow(
+			"Workflow retry policy retryOn must be an error class, a predicate, or an array of them.",
+		);
+	});
+
 	it("declares a Calendar connection requirement", () => {
 		const definition = workflow({
 			name: "Schedule Follow-up",
@@ -1457,6 +1804,81 @@ describe("workflow", () => {
 		expect(stdoutSpy).not.toHaveBeenCalled();
 	});
 
+	it("writes retryable and terminal error envelopes", async () => {
+		const retryable = workflow({
+			name: "Retryable workflow",
+			description: "Classifies temporary failures",
+			triggers: [events.notionPageCreated()],
+			handler: () => {
+				throw new RetryableError("try later", { retryAfterMs: 5_000 });
+			},
+		});
+
+		await expect(retryable.handler(event)).rejects.toBeInstanceOf(ExecutionError);
+		expect(stdoutSpy).toHaveBeenLastCalledWith(
+			expect.stringContaining(
+				`<__notion_output__>{"_tag":"error","error":{"_tag":"retryable","name":"RetryableError","message":"try later"`,
+			),
+		);
+		expect(stdoutSpy).toHaveBeenLastCalledWith(expect.stringContaining(`"retryAfterMs":5000`));
+
+		stdoutSpy.mockClear();
+		const fatal = workflow({
+			name: "Fatal workflow",
+			description: "Classifies permanent failures",
+			triggers: [events.notionPageCreated()],
+			handler: () => {
+				throw new FatalError("stop now");
+			},
+		});
+
+		await expect(fatal.handler(event)).rejects.toBeInstanceOf(ExecutionError);
+		expect(stdoutSpy).toHaveBeenLastCalledWith(
+			expect.stringContaining(
+				`<__notion_output__>{"_tag":"error","error":{"_tag":"terminal","name":"FatalError","message":"stop now"`,
+			),
+		);
+	});
+
+	it("reports a step failure that used its retries as terminal", async () => {
+		const definition = workflow({
+			name: "Step failure",
+			description: "Does not retry the run after a step exhausts its retries",
+			triggers: [events.notionPageCreated()],
+			handler: async (_event, context) => {
+				await context.step("Fail", { retry: { maxAttempts: 1 } }, () => {
+					throw new Error("step down");
+				});
+			},
+		});
+
+		await expect(definition.handler(event)).rejects.toBeInstanceOf(ExecutionError);
+		expect(stdoutSpy).toHaveBeenLastCalledWith(
+			expect.stringContaining(
+				`<__notion_output__>{"_tag":"error","error":{"_tag":"terminal","name":"Error","message":"step down"`,
+			),
+		);
+	});
+
+	it("reports failures outside steps not matched by the workflow retryOn as terminal", async () => {
+		const definition = workflow({
+			name: "Classified failure",
+			description: "Applies retryOn to failures outside steps",
+			triggers: [events.notionPageCreated()],
+			retry: { maxAttempts: 2, retryOn: RangeError },
+			handler: () => {
+				throw new TypeError("bug");
+			},
+		});
+
+		await expect(definition.handler(event)).rejects.toBeInstanceOf(ExecutionError);
+		expect(stdoutSpy).toHaveBeenLastCalledWith(
+			expect.stringContaining(
+				`<__notion_output__>{"_tag":"error","error":{"_tag":"terminal","name":"TypeError","message":"bug"`,
+			),
+		);
+	});
+
 	it("writes an error envelope and throws ExecutionError on failure", async () => {
 		const definition = workflow({
 			name: "Log Pages",