Diagnosing concurrency bugs.

01 / The idea

A passing schedule does not prove a shared update is safe.

The counter starts at 10. Picker A decrements 3; Picker B decrements 4. The expected result is 3. In a sequential schedule, both workers happen to read the latest value.

In the failing schedule, A reads 10 and computes 7. Before A writes, B reads 10 and computes 6. A writes 7; B writes 6. Both operations “ran,” but one update disappeared because the read-modify-write was not one indivisible decision.

Control the interleaving first; then make the shared snapshot visible.

// A read-modify-write can interleave when two workers share the counter.
export function simulateUnsafe(
	start: number,
	schedule: readonly ScheduleStep[] = unsafeSchedule
): Simulation {
	let available = start;
	const observed: Record<WorkerId, number | null> = { 'picker-a': null, 'picker-b': null };
	const computed: Record<WorkerId, number | null> = { 'picker-a': null, 'picker-b': null };
	const trace: TraceEntry[] = [];
	for (const [index, step] of schedule.entries()) {
		const before = available;
		if (step.action === 'read') {
			observed[step.worker] = available;
			trace.push({
				turn: index + 1,
				...step,
				availableBefore: before,
				availableAfter: available,
				localValue: available,
				note: `${step.worker} reads shared available`
			});
			continue;
		}
		if (step.action === 'compute') {
			const next = (observed[step.worker] ?? available) + jobs[step.worker];
			computed[step.worker] = next;
			trace.push({
				turn: index + 1,
				...step,
				availableBefore: before,
				availableAfter: available,
				localValue: next,
				note: `${step.worker} computes from its snapshot`
			});
			continue;
		}
		available = computed[step.worker] ?? available;
		trace.push({
			turn: index + 1,
			...step,
			availableBefore: before,
			availableAfter: available,
			localValue: available,
			note: `${step.worker} writes its stale snapshot`
		});
	}
	const expected = start + jobs['picker-a'] + jobs['picker-b'];
	return {
		start,
		available,
		expected,
		lostUnits: available - expected,
		trace,
		overlap: firstOverlappingRead(trace) !== null
	};
}

02 / See the shape

Separate the schedule, shared state, and worker-local value.

simulateUnsafe follows a schedule of worker actions. Each worker keeps its own observed and computed value while the simulation records the shared counter before and after every turn. simulateSerialized completes one worker’s critical section before the next worker reads.

export function simulateSerialized(
	start: number,
	order: readonly WorkerId[] = ['picker-a', 'picker-b']
): Simulation {
	let available = start;
	const trace: TraceEntry[] = [];
	let turn = 0;
	for (const worker of order) {
		const beforeRead = available;
		trace.push({
			turn: ++turn,
			worker,
			action: 'read',
			availableBefore: beforeRead,
			availableAfter: beforeRead,
			localValue: beforeRead,
			note: `${worker} reads while it owns the critical section`
		});
		const next = beforeRead + jobs[worker];
		trace.push({
			turn: ++turn,
			worker,
			action: 'compute',
			availableBefore: beforeRead,
			availableAfter: beforeRead,
			localValue: next,
			note: `${worker} computes before releasing the lock`
		});
		available = next;
		trace.push({
			turn: ++turn,
			worker,
			action: 'write',
			availableBefore: beforeRead,
			availableAfter: available,
			localValue: available,
			note: `${worker} writes before the next worker reads`
		});
	}
	const expected = start + jobs['picker-a'] + jobs['picker-b'];
	return { start, available, expected, lostUnits: available - expected, trace, overlap: false };
}

func SimulateSerialized(start int, order []WorkerID) Simulation {
	available := start
	trace := []TraceEntry{}
	turn := 0
	for _, worker := range order {
		before := available
		turn++
		trace = append(trace, TraceEntry{Turn: turn, Worker: worker, Action: Read, AvailableBefore: before, AvailableAfter: before, LocalValue: pointer(before), Note: string(worker) + " reads while it owns the critical section"})
		next := before + jobs[worker]
		turn++
		trace = append(trace, TraceEntry{Turn: turn, Worker: worker, Action: Compute, AvailableBefore: before, AvailableAfter: before, LocalValue: pointer(next), Note: string(worker) + " computes before releasing the lock"})
		available = next
		turn++
		trace = append(trace, TraceEntry{Turn: turn, Worker: worker, Action: Write, AvailableBefore: before, AvailableAfter: available, LocalValue: pointer(available), Note: string(worker) + " writes before the next worker reads"})
	}
	expected := start + jobs[PickerA] + jobs[PickerB]
	return Simulation{Start: start, Available: available, Expected: expected, LostUnits: available - expected, Trace: trace, Overlap: false}
}

type SafeInventory struct {
	mu        sync.Mutex
	available int
}

func (inventory *SafeInventory) Adjust(delta int) {
	inventory.mu.Lock()
	defer inventory.mu.Unlock()
	inventory.available += delta
}

func RunSafely(start int, deltas []int) int {
	inventory := &SafeInventory{available: start}
	var workers sync.WaitGroup
	workers.Add(len(deltas))
	for _, delta := range deltas {
		go func() {
			defer workers.Done()
			inventory.Adjust(delta)
		}()
	}
	workers.Wait()
	return inventory.available
}

03 / Follow the schedule

Watch a quiet run become an explainable race.

The frames begin with a schedule that passes by accident, choose the interleaving that loses 3 units, highlight the second worker’s shared read, and serialize the critical section. The count changes; the evidence stays visible.

What controlled diagnosis buys you

A deterministic trace narrows the space of possible causes.

04 / Try a decision

Choose evidence before changing timing.

The inventory count sometimes ends 3 units too high: one picker’s decrement went missing. You can make the race more likely, hide it with retries, or force the read-modify-write overlap. Which move should come first?

05 / Give it a real job

Use the trace to choose synchronization.

First identify the shared state and the critical operation. Then choose the ownership rule that fits: a mutex for a small critical section, an atomic operation for a single supported update, a channel or actor for one owner, or a transactional store for a durable boundary. The trace is diagnostic; it does not decide the architecture for you.

After the fix, replay the controlled schedule, run the real implementation under the race detector or stress harness, and assert the invariant that every worker’s update contributes. Keep the schedule or a close regression scenario where a future reader can find it.

type InventoryView = {
	available: number;
	expected: number;
	status: 'consistent' | 'lost-update';
	lastEvidence: string;
};

export function InventoryStatus({ inventory }: { inventory: InventoryView }) {
	return (
		<article aria-label="Inventory status">
			<strong>{inventory.available} units available</strong>
			<small>
				{inventory.status === 'consistent'
					? 'Workers agree'
					: `Investigate lost update: expected ${inventory.expected}`}
			</small>
			<p>{inventory.lastEvidence}</p>
		</article>
	);
}

06 / Recognize it elsewhere

Different symptoms point to different concurrency evidence.

Ask what is shared, what is ordered, and what the program promises under interleaving.

07 / Already in your toolbox

The tools answer different parts of the question.

A deterministic schedule explains a particular interleaving. A race detector reports unsynchronized memory access in the real program. A stress run explores many schedules. A mutex, atomic, channel, actor, or transaction enforces the rule. Use each tool for the claim it can actually support.

08 / The parts to watch

A plausible fix can leave the shared rule unclear.

09 / Make the call

Choose a diagnostic depth that matches the failure.

Make the interleaving repeatable before naming the fix.

Synchronize the whole operation whose correctness depends on a shared snapshot.

10 / Take the idea with you

Explain the lost units without saying “race condition.”

“Both workers read 10 before either wrote. A saved 7, then B saved 6 over it, so A’s 3 units disappeared and the count ended 3 too high. We forced that order in a test, put the read-modify-write behind a mutex, and replayed the same order until the count came out at 3.” That tells a reviewer the interleaving, the shared state, and the evidence for the fix. When they want the words, they are lost update, critical section, and controlled schedule.

Before moving on, jot down the four steps that lose the update, why a longer sleep would not prove anything, and one place in your own code where two callers read a value, change it, and write it back. A like counter or a cart total counts.