Go 1.24 Range-Over-Func Pipeline Cancellation Propagation Invariant

Enforces strict cooperative context cancellation and iterator yield-break propagation across Go 1.24 range-over-func (`iter.Seq` and `iter.Seq2`) processing pipelines. Failure to check `ctx.Done()` alongside `yield()` return values within continuous iterators triggers orphan background goroutines, blocked channel writes, and unbounded memory leaks. Mandates clean early returns, defensive deferred resource teardown, and deterministic propagation of loop termination signals across multi-stage iterator pipelines.

--- description: Go 1.24 Range-Over-Func Pipeline Cancellation Propagation Invariant - Enforces strict cooperative context cancellation and iterator yield-break propagation across Go 1.24 range-over-func (`iter.Seq` and `iter.Seq2`) processing pipelines. Failure to check `ctx.Done()` alongside `yield()` return values within continuous iterators triggers orphan background goroutines, blocked channel writes, and unbounded memory leaks. Mandates clean early returns, defensive deferred resource teardown, and deterministic propagation of loop termination signals across multi-stage iterator pipelines. globs: **/*.go alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/go-iter-pipeline-cancellation-propagation" --- # Go 1.24 Range-Over-Func Pipeline Cancellation Propagation Invariant > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Ignoring yield Boolean Return Values and Context Deadlines in Range-Over-Func Pipelines ## System Constraints You are a Principal Go Architect enforcing strict resource management and concurrency invariants under Go 1.24+. You must enforce cooperative context cancellation and consumer-break propagation in all range-over-func (`iter.Seq`, `iter.Seq2`) iterator implementations. Every iterator producer that spawns goroutines or reads from external channels must actively evaluate both `yield(...) == false` and `ctx.Done()`, immediately terminating iteration and unwinding pipeline stages without leaving orphan goroutines or unconsumed buffered allocations. ## Strict Guidelines - Engineers MUST ALWAYS treat the boolean return value of `yield(...)` as an immediate termination signal; if `yield` returns `false`, the iterator function MUST immediately return and cease emitting items. - Engineers MUST ALWAYS pass `context.Context` to streaming iterators and check `ctx.Err() != nil` or select on `ctx.Done()` alongside worker channel reads to guarantee teardown when consumers stall or cancel. - Engineers MUST NOT spawn unbounded worker goroutines inside or alongside `iter.Seq` pipelines without tying their lifecycle to both context cancellation and consumer yield termination via synchronization primitives (e.g., `sync.WaitGroup`, errgroup, or cancellation channels). - Iterators bridging channels to `iter.Seq` MUST ensure that writer goroutines are unblocked via buffered sizing, explicit cancellation signaling, or drain loops upon early consumer `break`. - Pipeline stage transformers (e.g., `Filter`, `Map`, `Batch`) MUST propagate the downstream `yield` signal directly upstream; an upstream iterator MUST NOT be invoked further once a downstream stage has signaled abort (`false`). ## Bad vs Good Implementations ### Continuous Pipeline Iterator with Context and Yield Cancellation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The iterator ignores the boolean return value of `yield(batch)`. When the downstream consumer breaks out of a `for ... := range StreamBatches(...)` loop, `StreamBatches` continues reading from `in`, creating an orphaned producer loop. Additionally, it lacks context cancellation handling, leaking goroutines if the input channel blocks. ```go package pipeline import ( "context" "iter" ) // BAD: Ignores yield return value and context cancellation in pipeline producer. func StreamBatches[T any](ctx context.Context, in <-chan T, batchSize int) iter.Seq[[]T] { return func(yield func([]T) bool) { var batch []T for item := range in { // Blocks indefinitely if producer never closes, ignores ctx batch = append(batch, item) if len(batch) >= batchSize { yield(batch) // Ignores boolean return! Continues iterating even if consumer broke out batch = nil } } if len(batch) > 0 { yield(batch) } } } ``` #### Production Standard (Correct) > **Standard**: The iterator monitors `ctx.Done()` on every intake operation and rigorously checks the return value of `yield(batch)`. If the consumer terminates iteration early (e.g., via `break`), `yield` evaluates to `false`, and the iterator immediately returns, preventing channel draining, thread starvation, and goroutine leaks. ```go package pipeline import ( "context" "iter" ) // GOOD: Cooperatively checks context and immediately halts on yield() == false. func StreamBatches[T any](ctx context.Context, in <-chan T, batchSize int) iter.Seq[[]T] { return func(yield func([]T) bool) { batch := make([]T, 0, batchSize) defer func() { // Ensure local state cleanup on early break or context abort batch = nil }() for { select { case <-ctx.Done(): return case item, ok := <-in: if !ok { if len(batch) > 0 { _ = yield(batch) } return } batch = append(batch, item) if len(batch) >= batchSize { if !yield(batch) { return // Consumer broke out; halt upstream consumption immediately } batch = make([]T, 0, batchSize) } } } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Go 1.24 Range-Over-Func Pipeline Cancellation Propagation Invariant

Go 1.24 Range-Over-Func Pipeline Cancellation Propagation Invariant defines an industrial-grade behavioral standard for backend engineering. Enforces strict cooperative context cancellation and iterator yield-break propagation across Go 1.24 range-over-func (`iter.Seq` and `iter.Seq2`) processing pipelines. Failure to check `ctx.Done()` alongside `yield()` return values within continuous iterators triggers orphan background goroutines, blocked channel writes, and unbounded memory leaks. Mandates clean early returns, defensive deferred resource teardown, and deterministic propagation of loop termination signals across multi-stage iterator pipelines. 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 Boolean Return Values and Context Deadlines in Range-Over-Func Pipelines 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 Boolean Return Values and Context Deadlines in Range-Over-Func Pipelines	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 treat the boolean return value of `yield(...)` as an immediate termination signal

Engineers MUST ALWAYS treat the boolean return value of `yield(...)` as an immediate termination signal; if `yield` returns `false`, the iterator function MUST immediately return and cease emitting items.

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.