[V0_FILE]typescriptreact:file="app/components/demo.tsx" "use client"; import { useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from "react"; import { SagaCodeWorkbench, type GutterMarkKind, type HighlightTone, } from "./saga-code-workbench"; type RunStatus = "running" | "rolling_back" | "rolled_back" | "completed"; type StepState = | "scheduled" | "running" | "succeeded" | "failed" | "skipped" | "queued" | "compensating" | "compensated"; type FailureMode = "none" | "step1" | "step2" | "step3"; type ForwardStepSnapshot = { id: string; label: string; state: StepState; order: number; }; type CompensationSnapshot = { id: string; label: string; forStepId: string; forStepLabel: string; state: StepState; stackPosition: number; }; type SagaSnapshot = { runId: string; accountId: string; seats: number; status: RunStatus; failAtStep: 1 | 2 | 3 | null; failedStep: number | null; failureReason: string | null; elapsedMs: number; startedAt: string; isTerminal: boolean; forwardSteps: ForwardStepSnapshot[]; compensationStack: CompensationSnapshot[]; }; type StartResponse = { runId: string; status: RunStatus; snapshot: SagaSnapshot; }; type ExecutionLogTone = "info" | "warn" | "success"; type ExecutionLogEntry = { id: string; tone: ExecutionLogTone; message: string; elapsedMs: number; }; type ExecutionLogDraft = Omit; export type SagaOrchestratorLineMap = { reserveSeatsAwait: number[]; reserveSeatsPush: number[]; captureInvoiceAwait: number[]; captureInvoicePush: number[]; provisionSeatsAwait: number[]; sendConfirmationAwait: number[]; fatalErrorGuard: number[]; rollbackLoop: number[]; rollbackPop: number[]; rollbackRun: number[]; returnCompleted: number[]; returnRolledBack: number[]; }; export type SagaStepLineMap = { shouldFailCheck: number[]; throwFatal: number[]; returnProvisioned: number[]; }; export type SagaCodeHighlightState = { caption: string; orchestratorActiveLines: Set; stepActiveLines: Set; orchestratorGutterMarks: Set; stepGutterMarks: Set; }; const FORWARD_PLACEHOLDER: ForwardStepSnapshot[] = [ { id: "reserveSeats", label: "Reserve seats", state: "scheduled", order: 1 }, { id: "captureInvoice", label: "Capture invoice", state: "scheduled", order: 2 }, { id: "provisionSeats", label: "Provision seats", state: "scheduled", order: 3 }, { id: "sendConfirmation", label: "Send confirmation", state: "scheduled", order: 4 }, ]; export const SAGA_DEMO_DEFAULTS = { accountId: "acct_acme", seats: 5, failureMode: "step3", } as const satisfies { accountId: string; seats: number; failureMode: FailureMode; }; const FAILURE_MODE_OPTIONS: Array<{ value: FailureMode; label: string }> = [ { value: "step1", label: "Step 1 - Reserve seats" }, { value: "step2", label: "Step 2 - Capture invoice" }, { value: "step3", label: "Step 3 - Provision seats" }, { value: "none", label: "No failure" }, ]; const FAILURE_MODE_TO_STEP: Record = { none: null, step1: 1, step2: 2, step3: 3, }; export function mapFailureModeToStep(failureMode: FailureMode): 1 | 2 | 3 | null { return FAILURE_MODE_TO_STEP[failureMode]; } const WORKFLOW_LABEL = `"use ${"workflow"}"`; const STEP_LABEL = `"use ${"step"}"`; const POLL_INTERVAL_MS = 200; const MAX_LOG_ENTRIES = 40; const FORWARD_STEP_LINE_KEYS: Record< string, { active: keyof SagaOrchestratorLineMap; done: Array; } > = { reserveSeats: { active: "reserveSeatsAwait", done: ["reserveSeatsAwait", "reserveSeatsPush"], }, captureInvoice: { active: "captureInvoiceAwait", done: ["captureInvoiceAwait", "captureInvoicePush"], }, provisionSeats: { active: "provisionSeatsAwait", done: ["provisionSeatsAwait"], }, sendConfirmation: { active: "sendConfirmationAwait", done: ["sendConfirmationAwait"], }, }; function addLines(target: Set, lines: number[]): void { for (const line of lines) { target.add(line); } } function lineSetToArray(lines: Set): number[] { return Array.from(lines).sort((a, b) => a - b); } function lineSetToGutterMarks( lines: Set, kind: GutterMarkKind = "success" ): Record { const marks: Record = {}; for (const line of lines) { marks[line] = kind; } return marks; } function mapSagaStatusToHighlightTone(snapshot: SagaSnapshot | null): HighlightTone { if (!snapshot) return "amber"; switch (snapshot.status) { case "completed": return "green"; case "rolling_back": case "rolled_back": return "red"; case "running": return snapshot.failedStep ? "red" : "amber"; } } function logRunStart( previousSnapshot: SagaSnapshot | null, currentSnapshot: SagaSnapshot ): ExecutionLogDraft[] { if (previousSnapshot) { return []; } return [ { tone: "info", message: `Run started for ${currentSnapshot.accountId} with ${currentSnapshot.seats} seats.`, elapsedMs: currentSnapshot.elapsedMs, }, ]; } function logStatusTransition( previousSnapshot: SagaSnapshot | null, currentSnapshot: SagaSnapshot ): ExecutionLogDraft[] { if (!previousSnapshot || previousSnapshot.status === currentSnapshot.status) { return []; } return [ { tone: currentSnapshot.status === "completed" || currentSnapshot.status === "rolled_back" ? "success" : "warn", message: `Status -> ${currentSnapshot.status}`, elapsedMs: currentSnapshot.elapsedMs, }, ]; } function logForwardStepTransitions( previousForwardSteps: ForwardStepSnapshot[] | undefined, currentForwardSteps: ForwardStepSnapshot[], elapsedMs: number ): ExecutionLogDraft[] { const entries: ExecutionLogDraft[] = []; const previousStepState = new Map(); if (previousForwardSteps) { for (const step of previousForwardSteps) { previousStepState.set(step.id, step.state); } } for (const step of currentForwardSteps) { const priorState = previousStepState.get(step.id); if (priorState === step.state) continue; if (step.state === "running") { entries.push({ tone: "info", message: `${step.label} running`, elapsedMs }); } if (step.state === "succeeded") { entries.push({ tone: "success", message: `${step.label} succeeded`, elapsedMs }); } if (step.state === "failed") { entries.push({ tone: "warn", message: `${step.label} failed with FatalError`, elapsedMs, }); } if (step.state === "skipped") { entries.push({ tone: "info", message: `${step.label} skipped`, elapsedMs }); } } return entries; } function logCompensationTransitions( previousCompensationStack: CompensationSnapshot[] | undefined, currentCompensationStack: CompensationSnapshot[], elapsedMs: number ): ExecutionLogDraft[] { const entries: ExecutionLogDraft[] = []; const previousCompensationState = new Map(); if (previousCompensationStack) { for (const step of previousCompensationStack) { previousCompensationState.set(step.id, step.state); } } for (const step of currentCompensationStack) { const priorState = previousCompensationState.get(step.id); if (priorState === step.state) continue; if (step.state === "compensating") { entries.push({ tone: "warn", message: `${step.label} compensating`, elapsedMs }); } if (step.state === "compensated") { entries.push({ tone: "success", message: `${step.label} compensated`, elapsedMs }); } } return entries; } export function getSagaCodeHighlightState(input: { snapshot: SagaSnapshot | null; orchestratorLineMap: SagaOrchestratorLineMap; stepLineMap: SagaStepLineMap; }): SagaCodeHighlightState { const { snapshot, orchestratorLineMap, stepLineMap } = input; const orchestratorActiveLines = new Set(); const stepActiveLines = new Set(); const orchestratorGutterMarks = new Set(); const stepGutterMarks = new Set(); if (!snapshot) { return { caption: "Start a run to trace forward execution and compensation unwind.", orchestratorActiveLines, stepActiveLines, orchestratorGutterMarks, stepGutterMarks, }; } for (const step of snapshot.forwardSteps) { const lineKey = FORWARD_STEP_LINE_KEYS[step.id]; if (!lineKey) continue; if (step.state === "succeeded") { for (const key of lineKey.done) { addLines(orchestratorGutterMarks, orchestratorLineMap[key]); } } if (step.state === "running") { addLines(orchestratorActiveLines, orchestratorLineMap[lineKey.active]); } } const provisionStep = snapshot.forwardSteps.find((step) => step.id === "provisionSeats"); const failedForwardStep = snapshot.forwardSteps.find((step) => step.state === "failed"); if (provisionStep?.state === "succeeded") { addLines(stepGutterMarks, stepLineMap.returnProvisioned); } if (failedForwardStep) { const failedStepLineKey = FORWARD_STEP_LINE_KEYS[failedForwardStep.id]; if (failedStepLineKey) { addLines(orchestratorActiveLines, orchestratorLineMap[failedStepLineKey.active]); } addLines(orchestratorActiveLines, orchestratorLineMap.fatalErrorGuard); addLines(stepActiveLines, stepLineMap.shouldFailCheck); addLines(stepActiveLines, stepLineMap.throwFatal); } const hasCompensations = snapshot.compensationStack.length > 0; const compensationIsRunning = snapshot.compensationStack.some( (step) => step.state === "compensating" ); const compensationDoneCount = snapshot.compensationStack.filter( (step) => step.state === "compensated" ).length; if (compensationDoneCount > 0) { addLines(orchestratorGutterMarks, orchestratorLineMap.rollbackPop); addLines(orchestratorGutterMarks, orchestratorLineMap.rollbackRun); } if (snapshot.status === "rolling_back") { addLines(orchestratorActiveLines, orchestratorLineMap.fatalErrorGuard); addLines(orchestratorActiveLines, orchestratorLineMap.rollbackLoop); if (hasCompensations && compensationIsRunning) { addLines(orchestratorActiveLines, orchestratorLineMap.rollbackPop); addLines(orchestratorActiveLines, orchestratorLineMap.rollbackRun); } } if (snapshot.status === "rolled_back") { addLines(orchestratorGutterMarks, orchestratorLineMap.fatalErrorGuard); addLines(orchestratorGutterMarks, orchestratorLineMap.rollbackLoop); addLines(orchestratorGutterMarks, orchestratorLineMap.rollbackPop); addLines(orchestratorGutterMarks, orchestratorLineMap.rollbackRun); addLines(orchestratorGutterMarks, orchestratorLineMap.returnRolledBack); } if (snapshot.status === "completed") { addLines(orchestratorGutterMarks, orchestratorLineMap.sendConfirmationAwait); addLines(orchestratorGutterMarks, orchestratorLineMap.returnCompleted); } let caption = "Forward execution in progress."; if (snapshot.status === "running") { const runningStep = snapshot.forwardSteps.find((step) => step.state === "running"); if (runningStep) { caption = `${runningStep.label} is currently executing.`; } if (failedForwardStep) { caption = "FatalError -> triggers compensation stack unwind (LIFO)."; } } if (snapshot.status === "rolling_back" || snapshot.status === "rolled_back") { caption = "FatalError -> triggers compensation stack unwind (LIFO)."; } if (snapshot.status === "completed") { caption = "No FatalError occurred. Saga completed without compensation."; } return { caption, orchestratorActiveLines, stepActiveLines, orchestratorGutterMarks, stepGutterMarks, }; } async function postJson( url: string, body: unknown, signal: AbortSignal ): Promise { const response = await fetch(url, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body), signal, }); let data: unknown; try { data = await response.json(); } catch { data = null; } if (signal.aborted) { throw new DOMException("Request aborted", "AbortError"); } if (!response.ok) { const message = data && typeof data === "object" && "error" in data ? String((data as { error?: unknown }).error ?? "Request failed") : "Request failed"; throw new Error(message); } return data as T; } async function getJson(url: string, signal: AbortSignal): Promise { const response = await fetch(url, { method: "GET", cache: "no-store", signal, }); let data: unknown; try { data = await response.json(); } catch { data = null; } if (signal.aborted) { throw new DOMException("Request aborted", "AbortError"); } if (!response.ok) { const message = data && typeof data === "object" && "error" in data ? String((data as { error?: unknown }).error ?? "Request failed") : "Request failed"; throw new Error(message); } return data as T; } export function SagaDemo({ orchestratorCode, orchestratorHtmlLines, orchestratorLineMap, stepCode, stepHtmlLines, stepLineMap, }: { orchestratorCode: string; orchestratorHtmlLines: string[]; orchestratorLineMap: SagaOrchestratorLineMap; stepCode: string; stepHtmlLines: string[]; stepLineMap: SagaStepLineMap; }) { const [failureMode, setFailureMode] = useState( SAGA_DEMO_DEFAULTS.failureMode ); const [runId, setRunId] = useState(null); const [snapshot, setSnapshot] = useState(null); const [executionLog, setExecutionLog] = useState([]); const [isStarting, setIsStarting] = useState(false); const [error, setError] = useState(null); const pollingRef = useRef | null>(null); const inFlightRef = useRef(false); const abortRef = useRef(null); const logScrollRef = useRef(null); const startButtonRef = useRef(null); const previousSnapshotRef = useRef(null); const hasScrolledRef = useRef(false); useEffect(() => { if (runId && !hasScrolledRef.current) { hasScrolledRef.current = true; const heading = document.getElementById("try-it-heading"); if (heading) { const top = heading.getBoundingClientRect().top + window.scrollY; window.scrollTo({ top, behavior: "smooth" }); } } if (!runId) { hasScrolledRef.current = false; } }, [runId]); const stopPolling = useCallback(() => { if (pollingRef.current) { clearInterval(pollingRef.current); pollingRef.current = null; } inFlightRef.current = false; }, []); const getAbortController = useCallback((): AbortController => { if (!abortRef.current || abortRef.current.signal.aborted) { abortRef.current = new AbortController(); } return abortRef.current; }, []); const appendLog = useCallback( (tone: ExecutionLogTone, message: string, elapsedMs: number) => { const entry: ExecutionLogEntry = { id: `${Date.now()}-${Math.random().toString(16).slice(2)}`, tone, message, elapsedMs, }; setExecutionLog((previous) => { const next = [...previous, entry]; return next.slice(-MAX_LOG_ENTRIES); }); }, [] ); useEffect(() => { const logElement = logScrollRef.current; if (!logElement) return; logElement.scrollTop = logElement.scrollHeight; }, [executionLog.length]); useEffect(() => { return () => { stopPolling(); abortRef.current?.abort(); abortRef.current = null; }; }, [stopPolling]); useEffect(() => { if (!snapshot) { previousSnapshotRef.current = null; return; } const previousSnapshot = previousSnapshotRef.current; const logEntries = [ ...logRunStart(previousSnapshot, snapshot), ...logStatusTransition(previousSnapshot, snapshot), ...logForwardStepTransitions( previousSnapshot?.forwardSteps, snapshot.forwardSteps, snapshot.elapsedMs ), ...logCompensationTransitions( previousSnapshot?.compensationStack, snapshot.compensationStack, snapshot.elapsedMs ), ]; for (const entry of logEntries) { appendLog(entry.tone, entry.message, entry.elapsedMs); } previousSnapshotRef.current = snapshot; }, [snapshot, appendLog]); const pollStatus = useCallback( (targetRunId: string) => { stopPolling(); pollingRef.current = setInterval(async () => { if (inFlightRef.current) { return; } inFlightRef.current = true; let signal: AbortSignal | null = null; try { signal = getAbortController().signal; const nextSnapshot = await getJson( `/api/mock/status?runId=${encodeURIComponent(targetRunId)}`, signal ); if (signal.aborted) { return; } setSnapshot(nextSnapshot); if (nextSnapshot.isTerminal) { stopPolling(); } } catch (pollError) { if ( signal?.aborted || (pollError instanceof Error && pollError.name === "AbortError") ) { return; } stopPolling(); setError( pollError instanceof Error ? pollError.message : "Polling failed" ); } finally { inFlightRef.current = false; } }, POLL_INTERVAL_MS); }, [getAbortController, stopPolling] ); const handleStart = async () => { setError(null); setExecutionLog([]); previousSnapshotRef.current = null; stopPolling(); abortRef.current?.abort(); abortRef.current = null; setIsStarting(true); const signal = getAbortController().signal; try { const response = await postJson("/api/mock/start", { accountId: SAGA_DEMO_DEFAULTS.accountId, seats: SAGA_DEMO_DEFAULTS.seats, failAtStep: mapFailureModeToStep(failureMode), }, signal); if (signal.aborted) { return; } setRunId(response.runId); setSnapshot(response.snapshot); if (!response.snapshot.isTerminal) { pollStatus(response.runId); } } catch (startError) { if ( signal.aborted || (startError instanceof Error && startError.name === "AbortError") ) { return; } setError(startError instanceof Error ? startError.message : "Start failed"); } finally { if (!signal.aborted) { setIsStarting(false); } } }; const handleReset = () => { stopPolling(); abortRef.current?.abort(); abortRef.current = null; previousSnapshotRef.current = null; setRunId(null); setSnapshot(null); setExecutionLog([]); setError(null); setFailureMode(SAGA_DEMO_DEFAULTS.failureMode); setIsStarting(false); setTimeout(() => { startButtonRef.current?.focus(); }, 0); }; const isActiveRun = Boolean(runId) && snapshot !== null && !snapshot.isTerminal; const isLocked = isStarting || isActiveRun; const forwardSteps = snapshot?.forwardSteps ?? FORWARD_PLACEHOLDER; const compensationStack = snapshot?.compensationStack ?? []; const rollbackLabel = useMemo(() => { if (!snapshot) return "Waiting to start"; switch (snapshot.status) { case "running": if (snapshot.failedStep) { return `FatalError thrown at step ${snapshot.failedStep}. Preparing rollback.`; } return "Forward execution in progress. Compensation stack is being built."; case "rolling_back": return `Rollback in progress. Unwinding stack in LIFO order after step ${snapshot.failedStep}.`; case "rolled_back": return "Rollback complete. Invoice refunded and seats released in reverse order."; case "completed": return "Upgrade completed. No rollback was needed."; } }, [snapshot]); const highlightState = useMemo( () => getSagaCodeHighlightState({ snapshot, orchestratorLineMap, stepLineMap, }), [snapshot, orchestratorLineMap, stepLineMap] ); const workbenchTone = useMemo( () => mapSagaStatusToHighlightTone(snapshot), [snapshot] ); return (

{error ? (

{error}

) : null}

Fail at

{snapshot?.status ?? "idle"} elapsed {snapshot ? `${snapshot.elapsedMs}ms` : "0ms"}

Defaults: {SAGA_DEMO_DEFAULTS.accountId}{" "} with {SAGA_DEMO_DEFAULTS.seats} seats.

{rollbackLabel}

Forward steps

{step.order}. {step.label}

Compensation stack (top executes first)

Handlers are pushed as forward steps succeed. FatalError unwinds in reverse order.

{compensationStack.length === 0 ? (

No compensation handlers queued yet.

) : (

{step.label}

compensates {step.forStepId}

)}

{executionLog.length === 0 ? (

Start a run to stream step-by-step execution updates.

) : (

{entry.message} +{entry.elapsedMs}ms

)}

{highlightState.caption}

); } type CardState = "active" | "done" | "pending"; function StepCard({ step, title, state, children, }: { step: number; title: string; state: CardState; children: ReactNode; }) { return (

{state === "done" ? ( ) : ( step )} {title}

{children}

); } function statusPillClass(status: RunStatus): string { switch (status) { case "running": return "border border-amber-700/40 bg-amber-700/20 text-amber-700"; case "rolling_back": return "border border-red-700/40 bg-red-700/10 text-red-700"; case "rolled_back": return "border border-red-700/30 bg-red-700/10 text-red-700"; case "completed": return "border border-green-700/40 bg-green-700/20 text-green-700"; } } function StatePill({ state }: { state: StepState }) { return ( {state} ); } function stateBadgeClass(state: StepState): string { switch (state) { case "scheduled": return "border-gray-500/60 bg-gray-500/10 text-gray-900"; case "running": return "border-amber-700/50 bg-amber-700/20 text-amber-700"; case "succeeded": return "border-green-700/50 bg-green-700/20 text-green-700"; case "failed": return "border-red-700/50 bg-red-700/10 text-red-700"; case "skipped": return "border-gray-500/60 bg-gray-500/10 text-gray-900"; case "queued": return "border-blue-700/50 bg-blue-700/10 text-blue-700"; case "compensating": return "border-red-700/50 bg-red-700/10 text-red-700"; case "compensated": return "border-green-700/50 bg-green-700/20 text-green-700"; } } function logTextClass(tone: ExecutionLogTone): string { switch (tone) { case "info": return "text-gray-900"; case "warn": return "text-amber-700"; case "success": return "text-green-700"; } } [V0_FILE]typescriptreact:file="app/components/saga-code-workbench.tsx" "use client"; import { useEffect, useMemo, useRef, useState } from "react"; export type HighlightTone = "amber" | "cyan" | "green" | "red"; export type GutterMarkKind = "success" | "fail"; type CopyState = "idle" | "copied" | "failed"; type HighlightStyle = { border: string; bg: string; text: string; }; const HIGHLIGHT_STYLES: Record = { amber: { border: "border-amber-700", bg: "bg-amber-700/15", text: "text-amber-700", }, cyan: { border: "border-cyan-700", bg: "bg-cyan-700/15", text: "text-cyan-700", }, green: { border: "border-green-700", bg: "bg-green-700/15", text: "text-green-700", }, red: { border: "border-red-700", bg: "bg-red-700/15", text: "text-red-700", }, }; const CHECKMARK_POINTS = "3,8.5 7,12.5 14,4.5"; type PaneState = { filename: string; label: string; code: string; htmlLines: string[]; activeLines: number[]; gutterMarks: Record; tone: HighlightTone; }; export type SagaCodeWorkbenchProps = { leftPane: PaneState; rightPane: PaneState; }; export function SagaCodeWorkbench({ leftPane, rightPane, }: SagaCodeWorkbenchProps) { return (

); } function CodePane({ filename, label, code, htmlLines, activeLines, gutterMarks, tone, }: PaneState) { const [copyState, setCopyState] = useState("idle"); const activeLineSet = useMemo(() => new Set(activeLines), [activeLines]); const gutterMarkMap = useMemo( () => new Map(Object.entries(gutterMarks).map(([k, v]) => [Number(k), v])), [gutterMarks], ); const isFullReset = gutterMarkMap.size === 0 && activeLines.length === 0; const prevMarkRef = useRef>(new Map()); useEffect(() => { if (isFullReset) { prevMarkRef.current.clear(); return; } gutterMarkMap.forEach((kind, line) => { prevMarkRef.current.set(line, kind); }); }, [gutterMarkMap, isFullReset]); const highlightStyle = HIGHLIGHT_STYLES[tone]; const handleCopy = async () => { try { await navigator.clipboard.writeText(code); setCopyState("copied"); window.setTimeout(() => setCopyState("idle"), 1200); } catch { setCopyState("failed"); window.setTimeout(() => setCopyState("idle"), 1200); } }; return (

{filename}

{label}

          
            {htmlLines.map((lineHtml, index) => {
              const lineNumber = index + 1;
              const isActive = activeLineSet.has(lineNumber);
              const markKind = gutterMarkMap.get(lineNumber);
              const displayKind = isFullReset
                ? undefined
                : markKind ?? prevMarkRef.current.get(lineNumber);

              return (
                
                  
                    
                  
                  
                    {lineNumber}
                  
                   0 ? lineHtml : " ",
                    }}
                  />
                
              );
            })}

); } [V0_FILE]typescript:file="app/components/code-highlight-server.ts" import { highlight } from "sugar-high"; export function highlightCodeToHtmlLines(code: string): string[] { return highlight(code).split("\n"); } export function findLineNumbers(code: string, marker: string): number[] { const lines = code.split("\n"); const matches: number[] = []; for (let index = 0; index < lines.length; index += 1) { if (lines[index].includes(marker)) { matches.push(index + 1); } } return matches; } export function findBlockLineNumbers(code: string, startMarker: string): number[] { const lines = code.split("\n"); const startIndex = lines.findIndex((line) => line.includes(startMarker)); if (startIndex < 0) { return []; } const blockLines: number[] = []; let depth = 0; for (let index = startIndex; index < lines.length; index += 1) { const line = lines[index]; blockLines.push(index + 1); for (const char of line) { if (char === "{") { depth += 1; } if (char === "}") { depth -= 1; } } if (index > startIndex && depth <= 0) { break; } } return blockLines; } [V0_FILE]typescriptreact:file="app/layout.tsx" import type { Metadata } from "next"; import { Geist, Geist_Mono } from "next/font/google"; import "./globals.css"; const geistSans = Geist({ variable: "--font-geist-sans", subsets: ["latin"], }); const geistMono = Geist_Mono({ variable: "--font-geist-mono", subsets: ["latin"], }); export const metadata: Metadata = { title: "Saga Rollback \u2013 Workflow DevKit Example", description: "Demonstrates FatalError compensation stack rollback with Workflow DevKit", }; export default function RootLayout({ children, }: Readonly<{ children: React.ReactNode; }>) { return ( Skip to main content {children} ); } [V0_FILE]typescript:file="app/api/mock/start/route.ts" import { createApiErrorResponse, createApiSuccessResponse } from "../api"; import { buildMockSagaSnapshot, createMockSagaRun, type MockSagaFailAtStep, } from "../store"; type StartRequestBody = { accountId?: unknown; seats?: unknown; failAtStep?: unknown; }; function parseFailAtStep(value: unknown): MockSagaFailAtStep | null { if (value === null || value === undefined || value === "") { return null; } if (value === 1 || value === 2 || value === 3) { return value; } if (value === "1" || value === "2" || value === "3") { return Number(value) as 1 | 2 | 3; } return null; } export async function POST(request: Request) { let body: StartRequestBody; try { const parsed = await request.json(); if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) { return createApiErrorResponse( { code: "INVALID_REQUEST", message: "Request body must be a JSON object", }, { status: 400 } ); } body = parsed as StartRequestBody; } catch (error) { console.warn("[mock-saga] start_parse_failed", { attempted: "request.json()", failed: error instanceof Error ? error.message : String(error), }); return createApiErrorResponse( { code: "INVALID_REQUEST", message: "Invalid JSON body", }, { status: 400 } ); } const accountId = typeof body.accountId === "string" ? body.accountId.trim() : ""; if (!accountId) { return createApiErrorResponse( { code: "INVALID_REQUEST", message: "accountId is required", }, { status: 400 } ); } if ( typeof body.seats !== "number" || !Number.isInteger(body.seats) || body.seats < 1 || body.seats > 500 ) { return createApiErrorResponse( { code: "INVALID_REQUEST", message: "seats must be an integer between 1 and 500", }, { status: 400 } ); } const failAtStep = parseFailAtStep(body.failAtStep); if (body.failAtStep !== undefined && body.failAtStep !== null && failAtStep === null) { return createApiErrorResponse( { code: "INVALID_REQUEST", message: "failAtStep must be 1, 2, 3, or null", }, { status: 400 } ); } const runId = `mock-saga-${crypto.randomUUID().slice(0, 8)}`; const run = createMockSagaRun({ runId, accountId, seats: body.seats, failAtStep, }); const snapshot = buildMockSagaSnapshot(run, run.startedAtMs); return createApiSuccessResponse({ runId: run.id, status: snapshot.status, snapshot, message: "Saga run started", }); } [V0_FILE]typescript:file="app/api/mock/api.ts" import { NextResponse } from "next/server"; type ApiError = { code: string; message: string; }; export function createApiSuccessResponse>( fields: T, init?: ResponseInit ) { return NextResponse.json( { ok: true, ...fields, }, init ); } export function createApiErrorResponse(error: ApiError, init?: ResponseInit) { return NextResponse.json( { ok: false, error, }, init ); } [V0_FILE]typescript:file="app/api/mock/status/route.ts" import { createApiErrorResponse, createApiSuccessResponse } from "../api"; import { buildMockSagaSnapshot, getMockSagaRun } from "../store"; export async function GET(request: Request) { const { searchParams } = new URL(request.url); const runId = searchParams.get("runId")?.trim(); if (!runId) { return createApiErrorResponse( { code: "INVALID_REQUEST", message: "runId query parameter is required", }, { status: 400 } ); } const run = getMockSagaRun(runId); if (!run) { return createApiErrorResponse( { code: "NOT_FOUND", message: `Run not found: ${runId}`, }, { status: 404 } ); } const snapshot = buildMockSagaSnapshot(run); return createApiSuccessResponse(snapshot); } [V0_FILE]typescript:file="app/api/mock/store.ts" const FORWARD_STEP_DURATION_MS = 650; const COMPENSATION_STEP_DURATION_MS = 550; export type MockSagaRunStatus = | "running" | "rolling_back" | "rolled_back" | "completed"; export type MockSagaStepState = | "scheduled" | "running" | "succeeded" | "failed" | "skipped" | "queued" | "compensating" | "compensated"; export type MockSagaFailAtStep = 1 | 2 | 3 | null; type ForwardStepDefinition = { id: string; label: string; compensationId: string | null; compensationLabel: string | null; }; const FORWARD_STEPS: readonly ForwardStepDefinition[] = [ { id: "reserveSeats", label: "Reserve seats", compensationId: "releaseSeats", compensationLabel: "Release seats", }, { id: "captureInvoice", label: "Capture invoice", compensationId: "refundInvoice", compensationLabel: "Refund invoice", }, { id: "provisionSeats", label: "Provision seats", compensationId: "deprovisionSeats", compensationLabel: "Deprovision seats", }, { id: "sendConfirmation", label: "Send confirmation", compensationId: null, compensationLabel: null, }, ]; export type MockSagaRun = { id: string; accountId: string; seats: number; failAtStep: MockSagaFailAtStep; startedAt: string; startedAtMs: number; lastStatus: MockSagaRunStatus | null; }; export type MockForwardStepSnapshot = { id: string; label: string; state: MockSagaStepState; order: number; }; export type MockCompensationStepSnapshot = { id: string; label: string; forStepId: string; forStepLabel: string; state: MockSagaStepState; stackPosition: number; }; export type MockSagaSnapshot = { runId: string; accountId: string; seats: number; status: MockSagaRunStatus; failAtStep: MockSagaFailAtStep; failedStep: number | null; failureReason: string | null; elapsedMs: number; startedAt: string; isTerminal: boolean; forwardSteps: MockForwardStepSnapshot[]; compensationStack: MockCompensationStepSnapshot[]; }; declare global { // eslint-disable-next-line no-var var __mockSagaRuns: Map | undefined; } export const mockSagaRuns: Map = globalThis.__mockSagaRuns ?? (globalThis.__mockSagaRuns = new Map()); function toIso(timestampMs: number): string { return new Date(timestampMs).toISOString(); } function forwardStepStartMs(stepIndex: number, run: MockSagaRun): number { void run; return stepIndex * FORWARD_STEP_DURATION_MS; } function forwardStepEndMs(stepIndex: number, run: MockSagaRun): number { return forwardStepStartMs(stepIndex, run) + FORWARD_STEP_DURATION_MS; } function failureAtMs(run: MockSagaRun): number | null { if (run.failAtStep === null) { return null; } return forwardStepEndMs(run.failAtStep - 1, run); } function failedStepIsActive(run: MockSagaRun, elapsedMs: number): boolean { const failedStepEndMs = failureAtMs(run); if (failedStepEndMs === null) { return false; } return elapsedMs >= failedStepEndMs; } export function isMockSagaTerminal(status: MockSagaRunStatus): boolean { return status === "completed" || status === "rolled_back"; } export function createMockSagaRun(input: { runId: string; accountId: string; seats: number; failAtStep: MockSagaFailAtStep; nowMs?: number; }): MockSagaRun { const nowMs = input.nowMs ?? Date.now(); const run: MockSagaRun = { id: input.runId, accountId: input.accountId, seats: input.seats, failAtStep: input.failAtStep, startedAt: toIso(nowMs), startedAtMs: nowMs, lastStatus: null, }; mockSagaRuns.set(run.id, run); console.info("[mock-saga] run_created", { runId: run.id, accountId: run.accountId, seats: run.seats, failAtStep: run.failAtStep, startedAt: run.startedAt, }); return run; } export function getMockSagaRun(runId: string): MockSagaRun | undefined { return mockSagaRuns.get(runId); } function normalizeElapsedMs(startedAtMs: number, nowMs: number): number { return Math.max(0, nowMs - startedAtMs); } function computeForwardSteps(args: { elapsedMs: number; run: MockSagaRun; }): { steps: MockForwardStepSnapshot[]; queuedCompensations: MockCompensationStepSnapshot[]; failureReason: string | null; failedStep: number | null; } { const { elapsedMs, run } = args; const { failAtStep, accountId } = run; const steps: MockForwardStepSnapshot[] = []; const queuedCompensations: MockCompensationStepSnapshot[] = []; let failureReason: string | null = null; let failedStep: number | null = null; for (let index = 0; index < FORWARD_STEPS.length; index += 1) { const step = FORWARD_STEPS[index]; const stepNumber = index + 1; const stepStartMs = forwardStepStartMs(index, run); const stepEndMs = forwardStepEndMs(index, run); let state: MockSagaStepState; if (failAtStep !== null && stepNumber > failAtStep) { state = failedStepIsActive(run, elapsedMs) ? "skipped" : "scheduled"; } else if (elapsedMs < stepStartMs) { state = "scheduled"; } else if (elapsedMs < stepEndMs) { state = "running"; } else if (failAtStep !== null && stepNumber === failAtStep) { state = "failed"; failedStep = failAtStep; failureReason = `FatalError: ${step.label} failed for account ${accountId}`; } else { state = "succeeded"; } steps.push({ id: step.id, label: step.label, state, order: stepNumber, }); if ( state === "succeeded" && step.compensationId !== null && step.compensationLabel !== null ) { queuedCompensations.push({ id: step.compensationId, label: step.compensationLabel, forStepId: step.id, forStepLabel: step.label, state: "queued", stackPosition: 0, }); } } return { steps, queuedCompensations: queuedCompensations.reverse().map((entry, index) => ({ ...entry, stackPosition: index, })), failureReason, failedStep, }; } function computeRollbackProgress(args: { elapsedMs: number; run: MockSagaRun; queuedCompensations: MockCompensationStepSnapshot[]; }): { status: MockSagaRunStatus; compensationStack: MockCompensationStepSnapshot[]; } { const { elapsedMs, run, queuedCompensations } = args; if (run.failAtStep === null) { const lastForwardStepIndex = FORWARD_STEPS.length - 1; const forwardCompleteAtMs = lastForwardStepIndex >= 0 ? forwardStepEndMs(lastForwardStepIndex, run) : 0; return { status: elapsedMs >= forwardCompleteAtMs ? "completed" : "running", compensationStack: queuedCompensations, }; } const failedAtMs = failureAtMs(run)!; if (elapsedMs < failedAtMs) { return { status: "running", compensationStack: queuedCompensations, }; } if (queuedCompensations.length === 0) { return { status: "rolled_back", compensationStack: queuedCompensations, }; } const rollbackElapsedMs = elapsedMs - failedAtMs; const compensationStack = queuedCompensations.map((entry, index) => { const stepStartMs = index * COMPENSATION_STEP_DURATION_MS; const stepEndMs = stepStartMs + COMPENSATION_STEP_DURATION_MS; let state: MockSagaStepState = "queued"; if (rollbackElapsedMs >= stepEndMs) { state = "compensated"; } else if (rollbackElapsedMs >= stepStartMs) { state = "compensating"; } return { ...entry, state, }; }); const rollbackDurationMs = queuedCompensations.length * COMPENSATION_STEP_DURATION_MS; const status: MockSagaRunStatus = rollbackElapsedMs >= rollbackDurationMs ? "rolled_back" : "rolling_back"; return { status, compensationStack, }; } function logStatusTransition(run: MockSagaRun, snapshot: MockSagaSnapshot): void { if (run.lastStatus === snapshot.status) { return; } console.info("[mock-saga] run_status_transition", { runId: run.id, from: run.lastStatus, to: snapshot.status, elapsedMs: snapshot.elapsedMs, failedStep: snapshot.failedStep, failAtStep: run.failAtStep, forwardStepStates: snapshot.forwardSteps.map((step) => `${step.id}:${step.state}`), compensationStates: snapshot.compensationStack.map( (step) => `${step.id}:${step.state}` ), }); run.lastStatus = snapshot.status; } export function buildMockSagaSnapshot( run: MockSagaRun, nowMs: number = Date.now() ): MockSagaSnapshot { const elapsedMs = normalizeElapsedMs(run.startedAtMs, nowMs); const { steps, queuedCompensations, failureReason, failedStep } = computeForwardSteps({ elapsedMs, run, }); const rollback = computeRollbackProgress({ elapsedMs, run, queuedCompensations, }); const snapshot: MockSagaSnapshot = { runId: run.id, accountId: run.accountId, seats: run.seats, status: rollback.status, failAtStep: run.failAtStep, failedStep: failedStepIsActive(run, elapsedMs) ? failedStep : null, failureReason: failedStepIsActive(run, elapsedMs) ? failureReason : null, elapsedMs, startedAt: run.startedAt, isTerminal: isMockSagaTerminal(rollback.status), forwardSteps: steps, compensationStack: rollback.compensationStack, }; logStatusTransition(run, snapshot); return snapshot; } export const mockSagaTimings = { forwardStepDurationMs: FORWARD_STEP_DURATION_MS, compensationStepDurationMs: COMPENSATION_STEP_DURATION_MS, }; [V0_FILE]typescriptreact:file="app/page.tsx" import { findBlockLineNumbers, findLineNumbers, highlightCodeToHtmlLines, } from "./components/code-highlight-server"; import { SagaDemo, type SagaOrchestratorLineMap, type SagaStepLineMap, } from "./components/demo"; const wf = `"use ${"workflow"}"`; const st = `"use ${"step"}"`; const orchestratorCode = `import { FatalError } from "workflow"; type CompensationAction = "releaseSeats" | "refundInvoice"; export async function upgradeSeatsSaga( accountId: string, seats: number, failAtStep: 1 | 2 | 3 | null ) { ${wf}; const compensations: CompensationAction[] = []; try { await reserveSeats(accountId, seats, failAtStep === 1); compensations.push("releaseSeats"); await captureInvoice(accountId, seats, failAtStep === 2); compensations.push("refundInvoice"); await provisionSeats(accountId, seats, failAtStep === 3); await sendConfirmation(accountId, seats); return { status: "completed" as const }; } catch (error) { if (!(error instanceof FatalError)) throw error; while (compensations.length > 0) { const action = compensations.pop()!; await runCompensation(action, accountId); } return { status: "rolled_back" as const }; } }`; const stepCode = `import { FatalError } from "workflow"; async function provisionSeats( accountId: string, seats: number, shouldFail: boolean ) { ${st}; if (shouldFail) { throw new FatalError( \`provisionSeats failed for \${accountId} (\${seats} seats)\` ); } return { accountId, seats, status: "provisioned" as const }; }`; const orchestratorHtmlLines = highlightCodeToHtmlLines(orchestratorCode); const stepHtmlLines = highlightCodeToHtmlLines(stepCode); const orchestratorLineMap: SagaOrchestratorLineMap = { reserveSeatsAwait: findLineNumbers(orchestratorCode, "await reserveSeats("), reserveSeatsPush: findLineNumbers( orchestratorCode, 'compensations.push("releaseSeats")' ), captureInvoiceAwait: findLineNumbers( orchestratorCode, "await captureInvoice(" ), captureInvoicePush: findLineNumbers( orchestratorCode, 'compensations.push("refundInvoice")' ), provisionSeatsAwait: findLineNumbers( orchestratorCode, "await provisionSeats(" ), sendConfirmationAwait: findLineNumbers( orchestratorCode, "await sendConfirmation(" ), fatalErrorGuard: findLineNumbers( orchestratorCode, "if (!(error instanceof FatalError))" ), rollbackLoop: findBlockLineNumbers( orchestratorCode, "while (compensations.length > 0)" ), rollbackPop: findLineNumbers(orchestratorCode, "const action = compensations.pop()!"), rollbackRun: findLineNumbers( orchestratorCode, "await runCompensation(action, accountId)" ), returnCompleted: findLineNumbers( orchestratorCode, 'return { status: "completed" as const };' ), returnRolledBack: findLineNumbers( orchestratorCode, 'return { status: "rolled_back" as const };' ), }; const stepLineMap: SagaStepLineMap = { shouldFailCheck: findLineNumbers(stepCode, "if (shouldFail)"), throwFatal: findLineNumbers(stepCode, "throw new FatalError("), returnProvisioned: findLineNumbers( stepCode, 'return { accountId, seats, status: "provisioned" as const };' ), }; export default function Home() { return (

Workflow DevKit Example

Saga Rollback

Upgrade flow for SaaS seats: reserve capacity, capture invoice, then provision workspace. If provisioning throws a fatal error, the saga unwinds compensations in strict LIFO order: refund invoice, then release seats.

Try It

); } [V0_FILE]css:file="app/globals.css" @import "tailwindcss"; @theme { --color-background-100: #0a0a0a; --color-background-200: #171717; --color-gray-100: #1a1a1a; --color-gray-200: #1f1f1f; --color-gray-300: #292929; --color-gray-400: #737373; --color-gray-500: #525252; --color-gray-600: #404040; --color-gray-700: #262626; --color-gray-800: #171717; --color-gray-900: #a1a1a1; --color-gray-1000: #ededed; --color-blue-700: #0070F3; --color-red-700: #E5484D; --color-amber-700: #FFB224; --color-green-700: #46A758; --color-violet-700: #8B5CF6; --color-cyan-700: #06B6D4; --font-sans: var(--font-geist-sans); --font-mono: var(--font-geist-mono); } body { background: #0a0a0a; color: #ededed; font-family: var(--font-sans), -apple-system, BlinkMacSystemFont, sans-serif; } /* Prism token colors — Geist dark-mode palette Extracted from vercel.com/geist/code-block (dark theme) */ .token.keyword, .token.keyword.control-flow { color: #f75f8f; } /* pink — keywords */ .token.plain, .token.parameter, .token.punctuation, .token.plain-text, .token.property-access, .token.operator, .token.tag.punctuation { color: #ededed; } /* gray-1000 — plain text */ .token.function, .token.function.maybe-class-name { color: #bf7af0; } /* purple — functions */ .token.tag { color: #62c073; } /* green — JSX/HTML tags */ .token.literal-property.property { color: #ff6166; } /* red — properties */ .token.string, .token.boolean { color: #62c073; } /* green — strings, booleans */ .token.comment { color: #a1a1a1; } /* gray-900 — comments */ .token.class-name { color: #52a8ff; } /* blue — types */ .token.number { color: #62c073; } /* green — numbers */ .token.attr-name { color: #ff6166; } /* red — attribute names */ .token.attr-value { color: #62c073; } /* green — attribute values */ .token.builtin { color: #52a8ff; } /* blue — builtins */ .token.template-string { color: #62c073; } /* green — template literals */ .token.interpolation { color: #ededed; } /* gray-1000 — interpolation */ [V0_FILE]javascript:file="postcss.config.mjs" export default { plugins: { "@tailwindcss/postcss": {}, }, }; [V0_FILE]typescript:file="workflows/subscription-upgrade-saga.ts" import { FatalError } from "workflow"; type FailAtStep = 1 | 2 | 3 | null; type CompensationAction = | "releaseSeats" | "refundInvoice" | "deprovisionSeats"; type CompensationHandler = { action: CompensationAction; undo: () => Promise; }; export interface SubscriptionUpgradeResult { accountId: string; seats: number; status: "completed" | "rolled_back"; failedStep: FailAtStep; compensationOrder: CompensationAction[]; } export async function subscriptionUpgradeSaga( accountId: string, seats: number, failAtStep: FailAtStep = null ): Promise { "use workflow"; const compensations: CompensationHandler[] = []; let reservationId: string | null = null; let invoiceId: string | null = null; let entitlementId: string | null = null; try { reservationId = await reserveSeats(accountId, seats, failAtStep === 1); { const reservationToRelease = reservationId; compensations.push({ action: "releaseSeats", undo: () => releaseSeats(accountId, reservationToRelease), }); } invoiceId = await captureInvoice(accountId, seats, failAtStep === 2); { const invoiceToRefund = invoiceId; compensations.push({ action: "refundInvoice", undo: () => refundInvoice(accountId, invoiceToRefund), }); } entitlementId = await provisionSeats(accountId, seats, failAtStep === 3); { const entitlementToDeprovision = entitlementId; compensations.push({ action: "deprovisionSeats", undo: () => deprovisionSeats(accountId, entitlementToDeprovision), }); } await sendConfirmation(accountId, seats, invoiceId, entitlementId); return { accountId, seats, status: "completed", failedStep: null, compensationOrder: compensations.map((compensation) => compensation.action), }; } catch (error) { if (!(error instanceof FatalError)) { throw error; } const executedCompensations: CompensationAction[] = []; while (compensations.length > 0) { const compensation = compensations.pop()!; executedCompensations.push(compensation.action); await compensation.undo(); } return { accountId, seats, status: "rolled_back", failedStep: failAtStep, compensationOrder: executedCompensations, }; } } async function reserveSeats( accountId: string, seats: number, shouldFail: boolean ): Promise { "use step"; if (shouldFail) { throw new FatalError( `reserveSeats failed for account ${accountId} with ${seats} seats` ); } return `seat_reservation:${accountId}:${seats}`; } async function captureInvoice( accountId: string, seats: number, shouldFail: boolean ): Promise { "use step"; if (shouldFail) { throw new FatalError( `captureInvoice failed for account ${accountId} with ${seats} seats` ); } return `invoice:${accountId}:${seats}`; } async function provisionSeats( accountId: string, seats: number, shouldFail: boolean ): Promise { "use step"; if (shouldFail) { throw new FatalError( `provisionSeats failed for account ${accountId} with ${seats} seats` ); } return `entitlement:${accountId}:${seats}`; } async function sendConfirmation( accountId: string, seats: number, invoiceId: string, entitlementId: string ): Promise { "use step"; console.info("[subscription-upgrade-saga] confirmation_sent", { accountId, seats, invoiceId, entitlementId, }); } async function releaseSeats( accountId: string, reservationId: string | null ): Promise { "use step"; console.info("[subscription-upgrade-saga] release_seats", { accountId, reservationId, }); } async function refundInvoice( accountId: string, invoiceId: string | null ): Promise { "use step"; console.info("[subscription-upgrade-saga] refund_invoice", { accountId, invoiceId, }); } async function deprovisionSeats( accountId: string, entitlementId: string | null ): Promise { "use step"; console.info("[subscription-upgrade-saga] deprovision_seats", { accountId, entitlementId, }); } [V0_FILE]json:file="package.json" { "name": "saga", "version": "0.1.0", "private": true, "scripts": { "dev": "next dev", "build": "next build", "start": "next start", "lint": "next lint" }, "dependencies": { "next": "16.0.10", "react": "19.2.3", "react-dom": "19.2.3", "sugar-high": "^0.9.5", "workflow": "4.1.0-beta.53" }, "devDependencies": { "@tailwindcss/postcss": "^4", "@types/node": "^20", "@types/react": "^19", "@types/react-dom": "^19", "tailwindcss": "^4", "typescript": "^5" } } [V0_FILE]json:file="tsconfig.json" { "compilerOptions": { "target": "ES2017", "lib": ["dom", "dom.iterable", "esnext"], "allowJs": true, "skipLibCheck": true, "strict": true, "noEmit": true, "esModuleInterop": true, "module": "esnext", "moduleResolution": "bundler", "resolveJsonModule": true, "isolatedModules": true, "jsx": "react-jsx", "incremental": true, "plugins": [ { "name": "next" }, { "name": "workflow" } ], "paths": { "@/*": ["./*"] } }, "include": [ "next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts", ".next/dev/types/**/*.ts", "**/*.mts" ], "exclude": ["node_modules"] } [V0_FILE]typescript:file="next.config.ts" import { withWorkflow } from "workflow/next"; import type { NextConfig } from "next"; const nextConfig: NextConfig = {}; export default withWorkflow(nextConfig);