Go 1.24 Weak Pointer & Cleanup Invariant for Ephemeral Actor Caches

--- description: Go 1.24 Weak Pointer & Cleanup Invariant for Ephemeral Actor Caches - Enforces non-resurrecting ephemeral caching patterns using Go 1.24 weak pointers and runtime.AddCleanup. Eliminates strong cyclic reference retention and heap fragmentation across high-throughput actor goroutines by decoupling cleanup closures from cached heap allocations. globs: **/*.go alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/go124-weak-pointer-cache-finalization-invariant" --- # Go 1.24 Weak Pointer & Cleanup Invariant for Ephemeral Actor Caches > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Strong Reference Cycling and Object Resurrection in Concurrent Actor Caches ## System Constraints You are a Principal Go Systems Architect enforcing strict memory safety and garbage collection invariants under Go 1.24. Mandate that all ephemeral caches, canonicalization registries, and actor goroutine state leverage weak.Pointer[T] and runtime.AddCleanup, preventing object resurrection and memory fragmentation. ## Strict Guidelines - Engineers MUST ALWAYS store values in ephemeral actor caches as weak.Pointer[T] using weak.Make(val) rather than raw strong pointers. - Engineers MUST NOT capture the target heap pointer *T inside cleanup closures; cleanups MUST take primitive or detached identifiers as explicit arguments. - Code MUST dereference weak pointers via weak.Pointer.Value() and immediately evaluate a nil guard before passing payloads into actor channels or dispatch routines. - Services MUST adopt runtime.AddCleanup over legacy runtime.SetFinalizer to eradicate finalizer-induced object resurrection and execution order deadlocks. - Components NEVER establish circular strong references between cached value structures and actor state holders or parent supervisor contexts. ## Bad vs Good Implementations ### Ephemeral Actor Cache Registration with Cleanup #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Retaining strong pointers in the cache prevents garbage collection. Calling runtime.SetFinalizer with a closure capturing the struct creates a cyclic heap dependency and resurrects the object during GC, producing unbounded heap fragmentation under actor churn. ```go package cache import ( "runtime" "sync" ) type SessionActor struct { ID string Data []byte Registry *ActorRegistry // Cyclic pointer back to registry } type ActorRegistry struct { mu sync.RWMutex actors map[string]*SessionActor // Strong reference leak } func (r *ActorRegistry) Register(actor *SessionActor) { r.mu.Lock() defer r.mu.Unlock() r.actors[actor.ID] = actor actor.Registry = r // ANTI-PATTERN: runtime.SetFinalizer resurrects the object // Closure captures *SessionActor, keeping it pinned indefinitely runtime.SetFinalizer(actor, func(a *SessionActor) { a.Registry.mu.Lock() delete(a.Registry.actors, a.ID) a.Registry.mu.Unlock() }) } ``` #### Production Standard (Correct) > **Standard**: Go 1.24 weak.Make stores a non-owning pointer, allowing the GC to reclaim idle actors. runtime.AddCleanup receives the actor ID as a copied value argument without capturing the actor instance, breaking cyclic dependencies and eliminating resurrection cycles. ```go package cache import ( "runtime" "sync" "weak" ) type SessionActor struct { ID string Data []byte } type ActorRegistry struct { mu sync.RWMutex actors map[string]weak.Pointer[SessionActor] } func NewActorRegistry() *ActorRegistry { return &ActorRegistry{ actors: make(map[string]weak.Pointer[SessionActor]), } } func (r *ActorRegistry) Register(actor *SessionActor) { r.mu.Lock() defer r.mu.Unlock() // Store weak reference so GC can reclaim unreferenced actors r.actors[actor.ID] = weak.Make(actor) // Go 1.24 runtime.AddCleanup with decoupled identifier prevents resurrection runtime.AddCleanup(actor, func(id string) { r.mu.Lock() defer r.mu.Unlock() if wp, exists := r.actors[id]; exists && wp.Value() == nil { delete(r.actors, id) } }, actor.ID) } func (r *ActorRegistry) Get(id string) (*SessionActor, bool) { r.mu.RLock() wp, ok := r.actors[id] r.mu.RUnlock() if !ok { return nil, false } // Dereference and validate against GC collection val := wp.Value() if val == nil { return nil, false } return val, true } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Go 1.24 Weak Pointer & Cleanup Invariant for Ephemeral Actor Caches

Go 1.24 Weak Pointer & Cleanup Invariant for Ephemeral Actor Caches defines an industrial-grade behavioral standard for backend engineering. Enforces non-resurrecting ephemeral caching patterns using Go 1.24 weak pointers and runtime.AddCleanup. Eliminates strong cyclic reference retention and heap fragmentation across high-throughput actor goroutines by decoupling cleanup closures from cached heap allocations. 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: Strong Reference Cycling and Object Resurrection in Concurrent Actor Caches 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	Strong Reference Cycling and Object Resurrection in Concurrent Actor Caches	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 store values in ephemeral actor caches as weak.Pointer[T] using weak.Make(val) rather than raw strong pointers.

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.