Debugging state and control flow.

01 / The idea

A bad final state is a clue, not an explanation.

The order begins in cart. Paying moves it to paid; shipping moves it to shipped; delivery moves it to delivered. Cancellation should be terminal before delivery.

The ordinary sequence does not expose the mistake. Add cancel before deliver and the buggy transition accepts both shipped and cancelled as delivery sources. The failure is not “the order is weird.” It is a specific branch that admitted an impossible predecessor.

Reproduce the smallest sequence, then make each state transition visible.

// The first version has a control-flow bug: cancellation is treated as a
// delivery source as well as shipment.
export function applyEventBuggy(order: Order, event: OrderEvent): TransitionResult {
	if (event === 'pay' && order.phase === 'cart') {
		return accepted(order, event, 'cart → paid', 'paid');
	}
	if (event === 'ship' && order.phase === 'paid') {
		return accepted(order, event, 'paid → shipped', 'shipped');
	}
	if (event === 'cancel' && order.phase !== 'delivered') {
		return accepted(order, event, 'not delivered → cancelled', 'cancelled');
	}
	if (event === 'deliver' && (order.phase === 'shipped' || order.phase === 'cancelled')) {
		return accepted(order, event, 'shipped or cancelled → delivered', 'delivered');
	}
	return rejected(
		order,
		event,
		`${order.phase} cannot ${event}`,
		'event is not allowed from this phase'
	);
}

02 / See the shape

Separate reproduction, observation, and repair.

The system under test is a transition function. replay applies events in order. A trace entry records the step number, previous phase, event, selected branch, resulting phase, and whether the event was accepted. That gives the debugger a stable vocabulary before it edits code.

export function applyEvent(order: Order, event: OrderEvent): TransitionResult {
	if (event === 'pay' && order.phase === 'cart') {
		return accepted(order, event, 'cart → paid', 'paid');
	}
	if (event === 'ship' && order.phase === 'paid') {
		return accepted(order, event, 'paid → shipped', 'shipped');
	}
	if (event === 'cancel' && order.phase !== 'delivered') {
		return accepted(order, event, 'not delivered → cancelled', 'cancelled');
	}
	if (event === 'deliver' && order.phase === 'shipped') {
		return accepted(order, event, 'shipped → delivered', 'delivered');
	}
	return rejected(
		order,
		event,
		`${order.phase} cannot ${event}`,
		'event is not allowed from this phase'
	);
}

export function replay(
	events: readonly OrderEvent[],
	transition: (order: Order, event: OrderEvent) => TransitionResult = applyEvent
): Order {
	return events.reduce((order, event) => {
		const result = transition(order, event);
		return result.order;
	}, initialOrder);
}

func ApplyEvent(order Order, event OrderEvent) TransitionResult {
	if event == Pay && order.Phase == Cart {
		return accepted(order, event, "cart → paid", Paid)
	}
	if event == Ship && order.Phase == Paid {
		return accepted(order, event, "paid → shipped", Shipped)
	}
	if event == Cancel && order.Phase != Delivered {
		return accepted(order, event, "not delivered → cancelled", Cancelled)
	}
	if event == Deliver && order.Phase == Shipped {
		return accepted(order, event, "shipped → delivered", Delivered)
	}
	return rejected(order, event, string(order.Phase)+" cannot "+string(event), "event is not allowed from this phase")
}

func Replay(events []OrderEvent, transition func(Order, OrderEvent) TransitionResult) Order {
	order := initialOrder
	for _, event := range events {
		order = transition(order, event).Order
	}
	return order
}

func ApplyEvent(order Order, event OrderEvent) TransitionResult {
	if event == Pay && order.Phase == Cart {
		return accepted(order, event, "cart → paid", Paid)
	}
	if event == Ship && order.Phase == Paid {
		return accepted(order, event, "paid → shipped", Shipped)
	}
	if event == Cancel && order.Phase != Delivered {
		return accepted(order, event, "not delivered → cancelled", Cancelled)
	}
	if event == Deliver && order.Phase == Shipped {
		return accepted(order, event, "shipped → delivered", Delivered)
	}
	return rejected(order, event, string(order.Phase)+" cannot "+string(event), "event is not allowed from this phase")
}

func Replay(events []OrderEvent, transition func(Order, OrderEvent) TransitionResult) Order {
	order := initialOrder
	for _, event := range events {
		order = transition(order, event).Order
	}
	return order
}

03 / Follow the trace

Watch a final symptom become a local decision.

The frames replay one order in four states: a happy path, the reported failure, the exact bad branch, and the corrected replay. Notice how the diagnostic question gets smaller at each step.

What the trace buys you

A useful trace reduces ambiguity without turning every internal variable into public API.

04 / Try a decision

Choose the next diagnostic move.

The order ended delivered after cancellation. You can change code, change timing, or make the sequence and decisions observable. Which move gives you evidence first?

05 / Give it a real job

Keep the reproduction beside the fix.

A production debugger needs a safe way to capture the triggering input, the relevant state, and the decision path. That might be a structured log, a trace ID, a replayable command list, or a focused failing test. Choose a representation that helps the next person rerun the cause without copying an entire environment.

After changing one guard, replay the same sequence and compare the before/after trace. Then add a regression test for the smallest durable failure and a broader boundary check if the state machine has more terminal paths.

type OrderView = {
	id: string;
	phase: 'cart' | 'paid' | 'shipped' | 'delivered' | 'cancelled';
	lastTransition: string;
};

export function OrderStatus({ order }: { order: OrderView }) {
	return (
		<article aria-label={`${order.id} status`}>
			<strong>{order.phase}</strong>
			<small>Last transition: {order.lastTransition}</small>
		</article>
	);
}

06 / Recognize it elsewhere

Follow state and decisions wherever symptoms travel.

The same debugging shape appears outside an order workflow.

07 / Already in your toolbox

Breakpoints, logs, and tests are different views of evidence.

A breakpoint lets you inspect a live decision. A structured log preserves a selected slice of that decision. A minimal reproduction makes it repeatable. A regression test keeps the cause from returning. Good debugging moves from the broadest symptom toward the smallest stable explanation.

08 / The parts to watch

More output can make a failure harder to see.

09 / Make the call

Use the smallest evidence that can distinguish causes.

Reproduce before speculating.

Trace the state before changing the control flow.

10 / Take the idea with you

Explain the bug without saying “debugging.”

“A four-event report reduces to cancel → deliver. At step 2 the order was cancelled, and the delivery branch accepted it because its guard allowed two source phases. We narrowed the guard to shipped and replayed the same two events until deliver was rejected.” That tells a reviewer the reproduction, the branch, and the evidence for the fix. When they want the words, they are minimal reproduction, trace, and guard.

Before moving on, jot down why pay → ship → cancel → deliver was not the reproduction to keep, what the trace entry at step 2 says, and the last bug in your own code you fixed before you could make it happen twice.