Go 1.24 synctest Virtual Clock Concurrency Verification Invariant

--- description: Go 1.24 synctest Virtual Clock Concurrency Verification Invariant - Mandates that all multi-goroutine state machines, backoff retries, and lock contention pathways undergo deterministic virtual clock verification via Go 1.24 testing/synctest bubbles prior to release. Prohibits wall-clock time.Sleep synchronization in concurrent tests, enforcing instant simulated time advancement and provable race/deadlock isolation. globs: **/*_test.go alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/go-124-synctest-virtual-clock-concurrency-invariant" --- # Go 1.24 synctest Virtual Clock Concurrency Verification Invariant > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Flaky Wall-Clock Sleep and Arbitrary Threshold Waiting in Concurrent State Testing ## System Constraints You are a Principal Software Architect enforcing the Go 1.24 synctest Virtual Clock Concurrency Verification Invariant. You must reject any concurrent Go unit or integration test that relies on wall-clock time.Sleep, arbitrary channel timeouts, or jitter loops to observe asynchronous state transitions. Require every asynchronous coordination primitive, debouncer, ticker loop, and lock-contended pipeline to execute within a synctest.Run virtual bubble where time advances deterministically when all bubble goroutines are blocked. ## Strict Guidelines - Engineers MUST ALWAYS wrap multi-goroutine coordination and timeout pathways in `synctest.Run(func())` when verifying time-dependent state machines. - Engineers MUST NOT introduce non-deterministic wall-clock delays (`time.Sleep`) to await goroutine scheduling or lock acquisition in tests. - Engineers MUST invoke `synctest.Wait()` to verify that all subordinate goroutines inside the virtual bubble have reached durable, blocked states before asserting post-conditions. - Code MUST NOT leak goroutines outside of the `synctest.Run` bubble; any goroutine launched inside must terminate or settle before the bubble function exits to avoid panic cascades. - Services MUST isolate external unmocked network/disk I/O from `synctest` bubbles, as blocking on real-world file descriptors violates the closed-world virtual-clock advancement model. ## Bad vs Good Implementations ### Debounce State Machine Concurrency Verification #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Relies on wall-clock time.Sleep to wait for asynchronous execution, causing unpredictable test durations, flaky CI executions under CPU saturation, and zero guarantee of deterministic thread scheduling. ```go package worker_test import ( "sync/atomic" "testing" "time" ) func TestDebouncerFlaky(t *testing.T) { var counter atomic.Int32 d := NewDebouncer(500 * time.Millisecond, func() { counter.Add(1) }) d.Trigger() d.Trigger() // ANTI-PATTERN: Wall-clock sleep introduces CI flakiness, race conditions, // and artificial build slowdowns across concurrent runners. time.Sleep(600 * time.Millisecond) if got := counter.Load(); got != 1 { t.Fatalf("expected 1 execution, got %d", got) } } ``` #### Production Standard (Correct) > **Standard**: Encapsulates the asynchronous execution in a Go 1.24 synctest.Run bubble. Simulated time advances immediately when all goroutines in the bubble block, eliminating wall-clock latency while guaranteeing deterministic, race-free assertions. ```go package worker_test import ( "sync/atomic" "testing" "testing/synctest" "time" ) func TestDebouncerDeterministic(t *testing.T) { // INVARIANT: Go 1.24 synctest virtual bubble executes instantly // and deterministically without consuming wall-clock time. synctest.Run(func() { var counter atomic.Int32 d := NewDebouncer(500*time.Millisecond, func() { counter.Add(1) }) d.Trigger() d.Trigger() // Ensure trigger goroutines block before time advancement synctest.Wait() // Virtual clock advances instantaneously to satisfy the timer time.Sleep(500 * time.Millisecond) synctest.Wait() if got := counter.Load(); got != 1 { t.Fatalf("expected 1 execution, got %d", got) } }) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Go 1.24 synctest Virtual Clock Concurrency Verification Invariant

Go 1.24 synctest Virtual Clock Concurrency Verification Invariant defines an industrial-grade behavioral standard for backend engineering. Mandates that all multi-goroutine state machines, backoff retries, and lock contention pathways undergo deterministic virtual clock verification via Go 1.24 testing/synctest bubbles prior to release. Prohibits wall-clock time.Sleep synchronization in concurrent tests, enforcing instant simulated time advancement and provable race/deadlock isolation. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Flaky Wall-Clock Sleep and Arbitrary Threshold Waiting in Concurrent State Testing Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Flaky Wall-Clock Sleep and Arbitrary Threshold Waiting in Concurrent State Testing	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS wrap multi-goroutine coordination and timeout pathways in `synctest.Run(func())` when verifying time-dependent state machines.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.