Go 1.24 Weak Reference Cache Eviction Standard

--- description: Go 1.24 Weak Reference Cache Eviction Standard - Mandates the use of Go 1.24's native weak package to eliminate memory leaks and unbounded heap growth in high-throughput in-memory entity caches. Caches storing canonical entities must store weak.Pointer instances to permit timely runtime garbage collection, pairing retrievals with mandatory nil checks and deferred key pruning. globs: **/*.go alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/go-1-24-weak-reference-cache-standard" --- # Go 1.24 Weak Reference Cache Eviction Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Retaining Strong Pointers in In-Memory Caches Leading to Unbounded Heap Retention and GC Pressure ## System Constraints You are a Principal Go Architect enforcing the Go 1.24 Weak Reference Cache Eviction Standard. Prevent memory leaks by mandating Go 1.24 native weak pointers (weak.Pointer) for secondary in-memory indexes and deduplication caches. Strictly reject strong-pointer retaining caches that bypass runtime GC reclamation. ## Strict Guidelines - Engineers MUST ALWAYS utilize Go 1.24's 'weak.Make[T](ptr)' when storing non-authoritative entity references in memory lookup maps. - Engineers MUST ALWAYS test the result of 'wp.Value()' against nil before accessing the underlying object to handle concurrent or prior GC eviction. - Engineers MUST NOT store strong references to heap objects alongside weak references within the same eviction domain. - Services MUST implement asynchronous or opportunistically triggered tombstone cleaning for cache keys whose weak pointers resolve to nil. - Components NEVER assume an object remains pinned between consecutive invocations of 'wp.Value()'; the dereferenced strong pointer must be stored in a local variable for the duration of its use. ## Bad vs Good Implementations ### In-Memory Entity Cache: Strong Pointers vs Go 1.24 weak.Pointer #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Retaining strong pointers (*Entity) in the map roots all cached instances to the garbage collector heap graph. Even if the rest of the application finishes processing the entity, the cache keeps the entire byte slice allocated until manual eviction, driving the heap to exhaustion in high-throughput workloads. ```go package cache import ( "sync" ) type Entity struct { ID string Data []byte } // BAD: Storing strong pointers prevents the Go GC from reclaiming // inactive entities, causing unbounded memory growth under load. type StrongCache struct { mu sync.RWMutex items map[string]*Entity } func NewStrongCache() *StrongCache { return &StrongCache{items: make(map[string]*Entity)} } func (c *StrongCache) Put(id string, e *Entity) { c.mu.Lock() defer c.mu.Unlock() c.items[id] = e } func (c *StrongCache) Get(id string) *Entity { c.mu.RLock() defer c.mu.RUnlock() return c.items[id] } ``` #### Production Standard (Correct) > **Standard**: Go 1.24's weak.Pointer holds non-owning references. When all external caller references fall out of scope, the GC collects the entity automatically. On cache hit, wp.Value() securely creates a temporary strong pointer pinned to the local stack frame, pruning nil keys opportunistically. ```go package cache import ( "sync" "weak" ) type Entity struct { ID string Data []byte } // GOOD: Leveraging Go 1.24 weak.Pointer allows the GC to reclaim // entities whenever external consumers release their strong references. type WeakCache struct { mu sync.RWMutex items map[string]weak.Pointer[Entity] } func NewWeakCache() *WeakCache { return &WeakCache{items: make(map[string]weak.Pointer[Entity])} } func (c *WeakCache) Put(id string, e *Entity) { c.mu.Lock() defer c.mu.Unlock() c.items[id] = weak.Make(e) } func (c *WeakCache) Get(id string) (*Entity, bool) { c.mu.RLock() wp, ok := c.items[id] c.mu.RUnlock() if !ok { return nil, false } // Materialize strong pointer and pin locally val := wp.Value() if val == nil { // Opportunistic tombstone cleanup c.mu.Lock() delete(c.items, id) c.mu.Unlock() return nil, false } return val, true } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Go 1.24 Weak Reference Cache Eviction Standard

Go 1.24 Weak Reference Cache Eviction Standard defines an industrial-grade behavioral standard for backend engineering. Mandates the use of Go 1.24's native weak package to eliminate memory leaks and unbounded heap growth in high-throughput in-memory entity caches. Caches storing canonical entities must store weak.Pointer instances to permit timely runtime garbage collection, pairing retrievals with mandatory nil checks and deferred key pruning. 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: Retaining Strong Pointers in In-Memory Caches Leading to Unbounded Heap Retention and GC Pressure 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	Retaining Strong Pointers in In-Memory Caches Leading to Unbounded Heap Retention and GC Pressure	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 utilize Go 1.24's 'weak.Make[T](ptr)' when storing non-authoritative entity references in memory lookup maps.

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.