Go 1.24 Range-over-Func Stream Pipeline Memory-Bounded Invariant

--- description: Go 1.24 Range-over-Func Stream Pipeline Memory-Bounded Invariant - Enforces strict push and pull iterator contract adherence in Go 1.24+ range-over-func pipelines. Mandates immediate termination upon false yield returns and deterministic execution of iter.Pull cleanup stop functions to prevent goroutine leaks, uncollected channel buffers, and unbounded heap retention in high-throughput streams. globs: **/*.go alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/go-1-24-rangefunc-stream-memory-bounded-invariant" --- # Go 1.24 Range-over-Func Stream Pipeline Memory-Bounded Invariant > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Ignoring Yield Return False or Leaking iter.Pull Stop Closures Causing Goroutine Hangs and Heap Leaks ## System Constraints You are a Principal Go Engineer enforcing the Go 1.24 Range-over-Func Stream Pipeline Memory-Bounded Invariant. You must audit and construct Go iterator pipelines (iter.Seq and iter.Seq2) to guarantee that push iterators unconditionally halt execution and release downstream resources when yield() returns false. Furthermore, when converting push iterators to pull iterators via iter.Pull or iter.Pull2, you must ensure the paired stop() closure is deterministically deferred to prevent orphan producer goroutines, blocked channel operations, and persistent memory exhaustion. ## Strict Guidelines - Engineers MUST ALWAYS inspect the boolean result of yield(v) or yield(k, v) in push iterators (iter.Seq/iter.Seq2) and return immediately when false to honor consumer early breaks. - Engineers MUST ALWAYS pair iter.Pull and iter.Pull2 invocations with a deterministic defer stop() to prevent leaking the internal producer goroutine and its associated channel buffers. - Engineers MUST NOT perform buffered batching or resource allocations across yield invocations without scoped defer-cleanup or explicit break checks prior to allocation. - Code SHOULD prefer push iterators (iter.Seq[V]) for standard stream transformations to eliminate the goroutine context switch and synchronization overhead inherent in iter.Pull. - Components NEVER execute blocking network or disk I/O downstream inside a push iterator after yield() returns false. ## Bad vs Good Implementations ### Push Iterator Yield Exhaustion and Resource Cleanup #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: When the caller breaks early from a range loop over this iterator, yield() returns false. Ignoring this return value causes the iterator to keep reading from the database cursor, wasting network bandwidth, CPU, and holding database connections unnecessarily. ```go package stream import ( "context" "database/sql" "iter" ) // Bad: Ignores yield return value, causing continued iteration and leaked rows cursor func ScanEvents(ctx context.Context, db *sql.DB) iter.Seq[string] { return func(yield func(string) bool) { rows, err := db.QueryContext(ctx, "SELECT payload FROM events") if err != nil { return } defer rows.Close() for rows.Next() { var payload string if err := rows.Scan(&payload); err != nil { return } // VIOLATION: Return value of yield ignored; loop continues scanning // even if the caller broke out of the for-range loop early. yield(payload) } } } ``` #### Production Standard (Correct) > **Standard**: Evaluating !yield(payload) ensures that the moment the consumer breaks from iteration, the iterator immediately returns, invoking defer rows.Close() and releasing DB resources without processing remaining records. ```go package stream import ( "context" "database/sql" "iter" ) // Good: Immediately halts and allows defer rows.Close() to execute upon false yield func ScanEvents(ctx context.Context, db *sql.DB) iter.Seq[string] { return func(yield func(string) bool) { rows, err := db.QueryContext(ctx, "SELECT payload FROM events") if err != nil { return } defer rows.Close() for rows.Next() { select { case <-ctx.Done(): return default: } var payload string if err := rows.Scan(&payload); err != nil { return } // Complies: Halts immediately if consumer signals break via false if !yield(payload) { return } } } } ``` ### Pull Iterator Deterministic Lifecycle and Stop Management #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: iter.Pull spawns an internal goroutine to run the push iterator. Failing to capture and invoke stop() via defer ensures that seq1's internal goroutine remains suspended indefinitely on a channel send, causing a permanent memory and goroutine leak. ```go package stream import "iter" // Bad: Omits stop() invocation when breaking early, permanently leaking iter.Pull goroutine func MergeStreams[T any](seq1, seq2 iter.Seq[T]) []T { next1, _ := iter.Pull(seq1) // VIOLATION: Leaked producer goroutine next2, stop2 := iter.Pull(seq2) defer stop2() var merged []T for range 10 { v1, ok1 := next1() if ok1 { merged = append(merged, v1) } v2, ok2 := next2() if ok2 { merged = append(merged, v2) } } return merged } ``` #### Production Standard (Correct) > **Standard**: Explicitly pairing each iter.Pull call with defer stop() ensures that whether the consumer finishes the loop or exits early, the internal coroutine/goroutine is signaled to clean up and avoid channel deadlock or heap leakage. ```go package stream import "iter" // Good: Guarantees every iter.Pull instance is cleanly terminated via defer stop() func MergeStreams[T any](seq1, seq2 iter.Seq[T]) []T { next1, stop1 := iter.Pull(seq1) defer stop1() next2, stop2 := iter.Pull(seq2) defer stop2() merged := make([]T, 0, 20) for range 10 { v1, ok1 := next1() if ok1 { merged = append(merged, v1) } v2, ok2 := next2() if ok2 { merged = append(merged, v2) } if !ok1 && !ok2 { break } } return merged } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Go 1.24 Range-over-Func Stream Pipeline Memory-Bounded Invariant

Go 1.24 Range-over-Func Stream Pipeline Memory-Bounded Invariant defines an industrial-grade behavioral standard for backend engineering. Enforces strict push and pull iterator contract adherence in Go 1.24+ range-over-func pipelines. Mandates immediate termination upon false yield returns and deterministic execution of iter.Pull cleanup stop functions to prevent goroutine leaks, uncollected channel buffers, and unbounded heap retention in high-throughput streams. 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: Ignoring Yield Return False or Leaking iter.Pull Stop Closures Causing Goroutine Hangs and Heap Leaks 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	Ignoring Yield Return False or Leaking iter.Pull Stop Closures Causing Goroutine Hangs and Heap Leaks	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 inspect the boolean result of yield(v) or yield(k, v) in push iterators (iter.Seq/iter.Seq2) and return immediately when false to honor consumer early breaks.

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.