1. Pick one shared invariant.
2. State the concurrent actors that can touch it.
3. State the allowed outcomes.
4. State the forbidden outcomes.
5. Create a tiny harness that amplifies the dangerous interleaving.
6. Run it repeatedly.
7. Fix the design, not only the test.
8. Replace sleep-based waiting with explicit synchronization.
9. Add one liveness assertion.
10. Document the ownership rule in code review notes.

assertThat(finalState).isNotEqualTo(ILLEGAL_STATE);
assertThat(duplicates).isZero();
assertThat(violations).isEmpty();

assertTimeoutPreemptively(Duration.ofSeconds(2), () -> service.shutdownGracefully());

final class RaceHarness {
    static void runConcurrently(int actors, Runnable task) throws InterruptedException {
        var ready = new CountDownLatch(actors);
        var start = new CountDownLatch(1);
        var done = new CountDownLatch(actors);
        var failures = new ConcurrentLinkedQueue<Throwable>();

        for (int i = 0; i < actors; i++) {
            Thread.ofPlatform().start(() -> {
                ready.countDown();
                try {
                    start.await();
                    task.run();
                } catch (Throwable t) {
                    failures.add(t);
                } finally {
                    done.countDown();
                }
            });
        }

        ready.await();
        start.countDown();

        if (!done.await(5, TimeUnit.SECONDS)) {
            throw new AssertionError("concurrent task did not finish");
        }

        if (!failures.isEmpty()) {
            var error = new AssertionError("concurrent task failed");
            failures.forEach(error::addSuppressed);
            throw error;
        }
    }
}

@Test
void approvalShouldHappenOnlyOnce() throws Exception {
    var repository = new InMemoryCaseRepository();
    var service = new CaseApprovalService(repository);

    var caseId = repository.createPendingCase();

    RaceHarness.runConcurrently(16, () -> service.approve(caseId, "supervisor-1"));

    var history = repository.history(caseId);

    assertThat(history)
        .filteredOn(e -> e.type().equals("CASE_APPROVED"))
        .hasSize(1);
}

@Test
void idempotencyKeyShouldNotBeConsumedTwice() throws Exception {
    for (int iteration = 0; iteration < 10_000; iteration++) {
        var store = new IdempotencyStore();
        var accepted = new AtomicInteger();

        RaceHarness.runConcurrently(2, () -> {
            if (store.tryStart("cmd-123")) {
                accepted.incrementAndGet();
            }
        });

        assertThat(accepted.get())
            .as("iteration %s", iteration)
            .isEqualTo(1);
    }
}

record Outcome(int actor1Result, int actor2Result, int finalValue) {}

@Test
void concurrentIncrementOutcomeShouldNeverLoseBothUpdates() throws Exception {
    var outcomes = new ConcurrentHashMap<Outcome, AtomicInteger>();

    for (int i = 0; i < 20_000; i++) {
        var counter = new AtomicInteger(0);
        var r1 = new AtomicInteger();
        var r2 = new AtomicInteger();

        RaceHarness.runConcurrently(2, new Runnable() {
            final AtomicInteger actor = new AtomicInteger();

            @Override
            public void run() {
                if (actor.getAndIncrement() == 0) {
                    r1.set(counter.incrementAndGet());
                } else {
                    r2.set(counter.incrementAndGet());
                }
            }
        });

        var outcome = new Outcome(r1.get(), r2.get(), counter.get());
        outcomes.computeIfAbsent(outcome, __ -> new AtomicInteger()).incrementAndGet();
    }

    assertThat(outcomes.keySet())
        .allMatch(o -> o.finalValue() == 2);
}

// Conceptual example. Real jcstress tests use jcstress annotations.
final class PublicationExample {
    int data;
    boolean ready;

    void writer() {
        data = 42;
        ready = true;
    }

    int reader() {
        if (ready) {
            return data;
        }
        return -1;
    }
}

ready observed as true, but data observed as 0

final class SafePublicationExample {
    int data;
    volatile boolean ready;

    void writer() {
        data = 42;
        ready = true;
    }

    int reader() {
        if (ready) {
            return data;
        }
        return -1;
    }
}

class ReportService {
    CompletableFuture<Report> generate(String caseId) {
        return CompletableFuture.supplyAsync(() -> loadReport(caseId));
    }
}

final class ReportService {
    private final Executor executor;
    private final ReportRepository repository;

    ReportService(Executor executor, ReportRepository repository) {
        this.executor = executor;
        this.repository = repository;
    }

    CompletableFuture<Report> generate(String caseId) {
        return CompletableFuture.supplyAsync(() -> repository.load(caseId), executor);
    }
}

final class DirectExecutor implements Executor {
    @Override
    public void execute(Runnable command) {
        command.run();
    }
}

@Test
void reportGenerationUsesRepository() {
    var service = new ReportService(new DirectExecutor(), new FakeReportRepository());

    var report = service.generate("case-1").join();

    assertThat(report.caseId()).isEqualTo("case-1");
}

@Test
void reportGenerationCompletesOnExecutor() {
    try (var executor = Executors.newFixedThreadPool(4)) {
        var service = new ReportService(executor, new SlowReportRepository());

        var future = service.generate("case-1");

        assertThat(future.join().caseId()).isEqualTo("case-1");
    }
}

Thread.sleep(5_000);
assertThat(retryCount.get()).isEqualTo(3);

record RetryPolicy(int maxAttempts, Duration baseDelay) {}

interface Sleeper {
    void sleep(Duration duration) throws InterruptedException;
}

final class RetryExecutor {
    private final RetryPolicy policy;
    private final Sleeper sleeper;

    RetryExecutor(RetryPolicy policy, Sleeper sleeper) {
        this.policy = policy;
        this.sleeper = sleeper;
    }

    <T> T execute(Callable<T> action) throws Exception {
        Exception last = null;
        for (int attempt = 1; attempt <= policy.maxAttempts(); attempt++) {
            try {
                return action.call();
            } catch (Exception e) {
                last = e;
                if (attempt == policy.maxAttempts()) {
                    throw e;
                }
                sleeper.sleep(policy.baseDelay());
            }
        }
        throw last;
    }
}

@Test
void retrySleepsBetweenAttemptsWithoutRealTime() {
    var slept = new ArrayList<Duration>();
    var retry = new RetryExecutor(
        new RetryPolicy(3, Duration.ofMillis(250)),
        slept::add
    );

    var attempts = new AtomicInteger();

    assertThatThrownBy(() -> retry.execute(() -> {
        attempts.incrementAndGet();
        throw new IOException("temporary");
    })).isInstanceOf(IOException.class);

    assertThat(attempts.get()).isEqualTo(3);
    assertThat(slept).containsExactly(Duration.ofMillis(250), Duration.ofMillis(250));
}

try {
    queue.take();
} catch (InterruptedException ignored) {
    // bad: interruption swallowed
}

final class Worker implements Runnable {
    private final BlockingQueue<String> queue;
    private final AtomicBoolean stopped = new AtomicBoolean();

    Worker(BlockingQueue<String> queue) {
        this.queue = queue;
    }

    @Override
    public void run() {
        try {
            while (!Thread.currentThread().isInterrupted()) {
                var item = queue.take();
                process(item);
            }
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        } finally {
            stopped.set(true);
        }
    }

    boolean stopped() {
        return stopped.get();
    }

    private void process(String item) {
        // work
    }
}

@Test
void workerStopsWhenInterrupted() throws Exception {
    var queue = new LinkedBlockingQueue<String>();
    var worker = new Worker(queue);
    var thread = Thread.ofPlatform().start(worker);

    thread.interrupt();
    thread.join(Duration.ofSeconds(2));

    assertThat(thread.isAlive()).isFalse();
    assertThat(worker.stopped()).isTrue();
}

final class ManagedExecutor implements AutoCloseable {
    private final ExecutorService executor;

    ManagedExecutor(ExecutorService executor) {
        this.executor = executor;
    }

    Future<?> submit(Runnable task) {
        if (executor.isShutdown()) {
            throw new RejectedExecutionException("executor closed");
        }
        return executor.submit(task);
    }

    @Override
    public void close() {
        executor.shutdown();
        try {
            if (!executor.awaitTermination(5, TimeUnit.SECONDS)) {
                executor.shutdownNow();
            }
        } catch (InterruptedException e) {
            executor.shutdownNow();
            Thread.currentThread().interrupt();
        }
    }
}

@Test
void closeStopsExecutorAndRejectsNewWork() {
    var managed = new ManagedExecutor(Executors.newFixedThreadPool(2));

    managed.close();

    assertThatThrownBy(() -> managed.submit(() -> {}))
        .isInstanceOf(RejectedExecutionException.class);
}

@Test
void closeDoesNotHangForeverWhenTaskIsStuck() {
    var started = new CountDownLatch(1);
    var executor = Executors.newSingleThreadExecutor();
    var managed = new ManagedExecutor(executor);

    managed.submit(() -> {
        started.countDown();
        LockSupport.park();
    });

    await(started);

    assertTimeout(Duration.ofSeconds(10), managed::close);
}

@Test
void transferShouldNotDeadlockWhenAccountsAreLockedInStableOrder() throws Exception {
    var service = new TransferService();
    var a = new AccountId("A");
    var b = new AccountId("B");

    assertTimeoutPreemptively(Duration.ofSeconds(3), () -> {
        RaceHarness.runConcurrently(2, new Runnable() {
            private final AtomicInteger actor = new AtomicInteger();

            @Override
            public void run() {
                if (actor.getAndIncrement() == 0) {
                    service.transfer(a, b, Money.of(10));
                } else {
                    service.transfer(b, a, Money.of(10));
                }
            }
        });
    });
}

void transfer(AccountId from, AccountId to, Money amount) {
    var first = from.compareTo(to) < 0 ? from : to;
    var second = from.compareTo(to) < 0 ? to : from;

    synchronized (lockFor(first)) {
        synchronized (lockFor(second)) {
            doTransfer(from, to, amount);
        }
    }
}

@Test
void noTenantShouldBeCompletelyStarved() throws Exception {
    var scheduler = new TenantAwareScheduler(4);
    var processed = new ConcurrentHashMap<String, AtomicInteger>();

    for (int i = 0; i < 10_000; i++) {
        scheduler.submit("hot", () -> increment(processed, "hot"));
    }

    for (String tenant : List.of("t1", "t2", "t3")) {
        for (int i = 0; i < 50; i++) {
            scheduler.submit(tenant, () -> increment(processed, tenant));
        }
    }

    scheduler.drain(Duration.ofSeconds(10));

    assertThat(processed.get("t1").get()).isGreaterThan(0);
    assertThat(processed.get("t2").get()).isGreaterThan(0);
    assertThat(processed.get("t3").get()).isGreaterThan(0);
}

private static void increment(Map<String, AtomicInteger> counters, String key) {
    counters.computeIfAbsent(key, __ -> new AtomicInteger()).incrementAndGet();
}

queue.depth{tenant}
queue.oldest_age{tenant}
work.processed{tenant}
work.rejected{tenant}
worker.utilization

@Test
void onlyCapacityReservationsShouldSucceed() throws Exception {
    var capacity = 10;
    var service = new ReservationService(capacity);
    var successes = new AtomicInteger();

    RaceHarness.runConcurrently(100, () -> {
        if (service.tryReserve("hearing-room-1")) {
            successes.incrementAndGet();
        }
    });

    assertThat(successes.get()).isEqualTo(capacity);
    assertThat(service.remaining("hearing-room-1")).isZero();
}

if not exists key:
    perform side effect
    save key

try insert key as STARTED
if conflict:
    return existing result or in-progress response
perform side effect
save final result

@Test
void sameCommandShouldProduceOneSideEffect() throws Exception {
    var sideEffects = new AtomicInteger();
    var service = new IdempotentCommandService(new InMemoryIdempotencyStore(), () -> {
        sideEffects.incrementAndGet();
        return "ok";
    });

    RaceHarness.runConcurrently(32, () -> service.handle("cmd-1"));

    assertThat(sideEffects.get()).isEqualTo(1);
}

@Test
void failedInProgressCommandShouldNotStayStuckForever() {
    var store = new InMemoryIdempotencyStore();
    var service = new IdempotentCommandService(store, () -> {
        throw new RuntimeException("downstream failed");
    });

    assertThatThrownBy(() -> service.handle("cmd-1"));

    assertThat(store.status("cmd-1"))
        .isIn(IdempotencyStatus.FAILED, IdempotencyStatus.RETRYABLE);
}

@Test
void actorShouldProcessOneMessageAtATime() throws Exception {
    var concurrentExecutions = new AtomicInteger();
    var maxConcurrent = new AtomicInteger();

    var actor = new CaseActor(command -> {
        int current = concurrentExecutions.incrementAndGet();
        maxConcurrent.accumulateAndGet(current, Math::max);
        try {
            Thread.sleep(10);
        } finally {
            concurrentExecutions.decrementAndGet();
        }
    });

    for (int i = 0; i < 100; i++) {
        actor.tell(new ApproveCase("case-1"));
    }

    actor.drain(Duration.ofSeconds(5));

    assertThat(maxConcurrent.get()).isEqualTo(1);
}

@Test
void actorShouldRejectWhenMailboxIsFull() {
    var actor = new CaseActor(1, command -> LockSupport.park());

    actor.tell(new ApproveCase("case-1"));

    assertThatThrownBy(() -> actor.tell(new ApproveCase("case-1")))
        .isInstanceOf(MailboxFullException.class);
}

@Test
void concurrentCacheMissShouldLoadOnce() throws Exception {
    var loads = new AtomicInteger();
    var cache = new SingleFlightCache<String, String>(key -> {
        loads.incrementAndGet();
        Thread.sleep(50);
        return "value-for-" + key;
    });

    RaceHarness.runConcurrently(32, () -> {
        assertThat(cache.get("case-1")).isEqualTo("value-for-case-1");
    });

    assertThat(loads.get()).isEqualTo(1);
}

@Test
void failedSingleFlightShouldNotPoisonKeyForever() {
    var attempts = new AtomicInteger();
    var cache = new SingleFlightCache<String, String>(key -> {
        if (attempts.incrementAndGet() == 1) {
            throw new IOException("temporary");
        }
        return "ok";
    });

    assertThatThrownBy(() -> cache.get("case-1"));
    assertThat(cache.get("case-1")).isEqualTo("ok");
}

PENDING_REVIEW
  -> APPROVED
  -> REJECTED

@Test
void concurrentTerminalTransitionsShouldHaveOneWinner() throws Exception {
    var repository = new CaseRepositoryWithOptimisticLocking();
    var service = new CaseWorkflowService(repository);
    var caseId = repository.create(PENDING_REVIEW);

    var results = new ConcurrentLinkedQueue<TransitionResult>();

    RaceHarness.runConcurrently(2, new Runnable() {
        private final AtomicInteger actor = new AtomicInteger();

        @Override
        public void run() {
            if (actor.getAndIncrement() == 0) {
                results.add(service.approve(caseId));
            } else {
                results.add(service.reject(caseId));
            }
        }
    });

    assertThat(results).filteredOn(TransitionResult::accepted).hasSize(1);
    assertThat(results).filteredOn(result -> !result.accepted()).hasSize(1);

    var state = repository.get(caseId).status();
    assertThat(state).isIn(APPROVED, REJECTED);
}

A case must have at most one terminal transition.

@Test
void outboxRowShouldBeClaimedByOneRelayWorker() throws Exception {
    var outbox = new InMemoryOutbox();
    outbox.insert(new OutboxMessage("msg-1", "CaseApproved"));

    var claimed = new ConcurrentLinkedQueue<OutboxMessage>();

    RaceHarness.runConcurrently(8, () -> {
        outbox.tryClaimNext("relay-1").ifPresent(claimed::add);
    });

    assertThat(claimed).hasSize(1);
}

@Test
void consumerShouldIgnoreDuplicateEvent() {
    var inbox = new InMemoryInbox();
    var projection = new CaseProjection();
    var consumer = new CaseApprovedConsumer(inbox, projection);

    var event = new EventEnvelope("event-1", "case-1", "CaseApproved");

    consumer.handle(event);
    consumer.handle(event);

    assertThat(projection.approvalCount("case-1")).isEqualTo(1);
}

@Test
void virtualThreadServiceShouldHandleManyBlockingCalls() throws Exception {
    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
        var service = new BlockingCaseLookupService(executor, new FakeSlowRepository());

        var futures = IntStream.range(0, 10_000)
            .mapToObj(i -> service.lookup("case-" + i))
            .toList();

        for (var future : futures) {
            assertThat(future.get(5, TimeUnit.SECONDS)).isNotNull();
        }
    }
}

@Test
void virtualThreadsShouldStillRespectDatabaseConnectionLimit() throws Exception {
    var maxConcurrentDbCalls = new AtomicInteger();
    var currentDbCalls = new AtomicInteger();

    var repository = new FakeRepository(() -> {
        int current = currentDbCalls.incrementAndGet();
        maxConcurrentDbCalls.accumulateAndGet(current, Math::max);
        try {
            Thread.sleep(20);
        } finally {
            currentDbCalls.decrementAndGet();
        }
    });

    var service = new CaseLookupService(repository, new Semaphore(20));

    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
        var futures = IntStream.range(0, 1_000)
            .mapToObj(i -> executor.submit(() -> service.lookup("case-" + i)))
            .toList();

        for (var future : futures) {
            future.get();
        }
    }

    assertThat(maxConcurrentDbCalls.get()).isLessThanOrEqualTo(20);
}

@Test
void failingSubtaskShouldCancelSiblingWork() throws Exception {
    var slowCancelled = new AtomicBoolean();

    assertThatThrownBy(() -> new CaseSummaryService().loadSummary(
        () -> { throw new IOException("case service down"); },
        () -> {
            try {
                Thread.sleep(Duration.ofSeconds(30));
                return "slow notes";
            } catch (InterruptedException e) {
                slowCancelled.set(true);
                Thread.currentThread().interrupt();
                throw e;
            }
        }
    )).isInstanceOf(IOException.class);

    assertThat(slowCancelled).isTrue();
}

@Test
void queueShouldRejectWhenFull() {
    var queue = new ArrayBlockingQueue<Command>(2);
    var dispatcher = new CommandDispatcher(queue);

    dispatcher.submit(new Command("1"));
    dispatcher.submit(new Command("2"));

    assertThatThrownBy(() -> dispatcher.submit(new Command("3")))
        .isInstanceOf(RejectedExecutionException.class);
}

@Test
void callerRunsPolicyShouldApplyBackpressure() {
    var executor = new ThreadPoolExecutor(
        1,
        1,
        0L,
        TimeUnit.MILLISECONDS,
        new ArrayBlockingQueue<>(1),
        new ThreadPoolExecutor.CallerRunsPolicy()
    );

    var callerThreadExecutions = new AtomicInteger();
    var callerThreadName = Thread.currentThread().getName();

    executor.submit(() -> LockSupport.parkNanos(TimeUnit.MILLISECONDS.toNanos(100)));
    executor.submit(() -> LockSupport.parkNanos(TimeUnit.MILLISECONDS.toNanos(100)));
    executor.submit(() -> {
        if (Thread.currentThread().getName().equals(callerThreadName)) {
            callerThreadExecutions.incrementAndGet();
        }
    });

    assertThat(callerThreadExecutions.get()).isEqualTo(1);
    executor.shutdownNow();
}

Thread.sleep(500);
assertThat(queue).isEmpty();

static void eventually(Duration timeout, Runnable assertion) {
    var deadline = System.nanoTime() + timeout.toNanos();
    AssertionError last = null;

    while (System.nanoTime() < deadline) {
        try {
            assertion.run();
            return;
        } catch (AssertionError e) {
            last = e;
            LockSupport.parkNanos(TimeUnit.MILLISECONDS.toNanos(10));
        }
    }

    if (last != null) {
        throw last;
    }
}

@Test
void workerEventuallyPublishesEvent() {
    worker.submit(new ApproveCase("case-1"));

    eventually(Duration.ofSeconds(2), () ->
        assertThat(eventSink.events()).extracting(Event::type).contains("CaseApproved")
    );
}

interface DelayHook {
    void pause(String point);

    static DelayHook none() {
        return point -> {};
    }
}

final class CaseWorkflowService {
    private final CaseRepository repository;
    private final DelayHook delayHook;

    CaseWorkflowService(CaseRepository repository, DelayHook delayHook) {
        this.repository = repository;
        this.delayHook = delayHook;
    }

    void approve(CaseId id) {
        var caze = repository.get(id);
        delayHook.pause("after-read-before-transition");
        caze.approve();
        repository.save(caze);
    }
}

@Test
void staleReadWindowShouldBeProtectedByVersion() throws Exception {
    var barrier = new CyclicBarrier(2);
    var delay = (DelayHook) point -> {
        if (point.equals("after-read-before-transition")) {
            await(barrier);
        }
    };

    var service = new CaseWorkflowService(new VersionedRepository(), delay);

    RaceHarness.runConcurrently(2, () -> service.approve(new CaseId("case-1")));

    assertThat(service.history("case-1", "CaseApproved")).hasSize(1);
}

@Test
void rejectedWorkShouldIncrementMetric() {
    var metrics = new FakeMetrics();
    var dispatcher = new BoundedDispatcher(1, metrics);

    dispatcher.submit(new Command("1"));

    assertThatThrownBy(() -> dispatcher.submit(new Command("2")))
        .isInstanceOf(RejectedExecutionException.class);

    assertThat(metrics.counter("command.rejected")).isEqualTo(1);
}

Thread.sleep(100);

verify(lock).lock();

assertThat(duplicates).isZero();

fast unit
integration
stress
soak
benchmark

Shared state
[ ] What state is shared?
[ ] Who owns it?
[ ] Is mutation confined, locked, atomic, or serialized?
[ ] Are multi-field invariants protected as one unit?

Visibility and ordering
[ ] What creates happens-before?
[ ] Is publication safe?
[ ] Are volatile/atomic/synchronized used correctly?
[ ] Is there any check-then-act race?

Safety
[ ] Can duplicate commands happen?
[ ] Can concurrent terminal transitions happen?
[ ] Can outbox/inbox duplicate processing happen?
[ ] Can cache stampede happen?
[ ] Can stale authorization/data leak happen?

Liveness
[ ] Can a lock be held while calling external code?
[ ] Can shutdown hang?
[ ] Can a queue grow without bound?
[ ] Can a worker starve a tenant/key?
[ ] Can cancellation fail to propagate?

Testing
[ ] Is there at least one race-oriented test for important invariants?
[ ] Are sleeps replaced by explicit synchronization?
[ ] Are timeout/cancellation/shutdown paths tested?
[ ] Are stress tests separated from fast unit tests?
[ ] Are forbidden outcomes explicit?

Operations
[ ] Are queue depth, lag, rejection, duplicate, and lock-wait signals visible?
[ ] Is there a thread dump / JFR / diagnostic plan?
[ ] Does overload fail boundedly?

boolean tryStart(String key);
void complete(String key, String result);
Optional<String> result(String key);

OPEN -> UNDER_REVIEW -> APPROVED
OPEN -> UNDER_REVIEW -> REJECTED