Free-Threaded Python 3.13 Concurrency Isolation and Safe Shared Memory Standard

--- description: Free-Threaded Python 3.13 Concurrency Isolation and Safe Shared Memory Standard - Enforces strict thread-safe request context isolation and synchronization primitives for FastAPI microservices running under free-threaded Python 3.13 (PEP 703). Prevents data races, torn reads, and cross-thread memory corruption caused by concurrent mutations to unsynchronized module-level state, standard collections, and shared object pools. globs: **/*.py, app/**/*.py, src/**/*.py, api/**/*.py alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/fastapi-python313-freethreaded-concurrency-isolation" --- # Free-Threaded Python 3.13 Concurrency Isolation and Safe Shared Memory Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unsynchronized Global State Mutation and Context Bleed Under Free-Threaded Execution ## System Constraints You are a Principal Software Architect enforcing Python 3.13 free-threaded (GIL-less) concurrency isolation across all FastAPI services. Mandate the complete elimination of unsynchronized mutable global state, unsafe in-memory singletons, and thread-unsafe caching patterns. Without the Global Interpreter Lock, standard operations like dict mutations and in-place list updates are subject to concurrent race conditions. You must enforce the use of contextvars for request contexts, explicit threading synchronization primitives (Lock, RLock) for shared memory, thread-safe concurrent data structures, and frozen immutable data models for cross-thread messaging. ## Strict Guidelines - Engineers MUST ALWAYS isolate request-scoped state using `contextvars.ContextVar` instead of module-level variables or threading.local across async thread pools. - Engineers MUST NOT mutate raw Python collections (`dict`, `set`, `list`) concurrently across threads without explicit synchronization via `threading.Lock` or `threading.RLock`. - Services MUST utilize immutable data structures (`dataclasses.dataclass(frozen=True)` or `pydantic.ConfigDict(frozen=True)`) when broadcasting or sharing data payloads between concurrent worker threads. - Code SHOULD leverage non-blocking thread-safe concurrent queues (`queue.Queue` or `queue.SimpleQueue`) instead of shared list-based buffers for inter-thread task distribution. - Components NEVER rely on Python's legacy GIL assumptions for thread-safe read-modify-write operations such as `counter += 1` or `cache.setdefault()`. ## Bad vs Good Implementations ### Request Context Isolation and Shared Counter Synchronization #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: In free-threaded Python 3.13, parallel OS threads executing pure Python code simultaneously mutate the global variable `current_tenant` and the standard dictionary `request_metrics`. This causes context bleed across concurrent client requests and non-deterministic memory/state corruption during concurrent read-modify-write operations on unshielded dictionaries. ```python from fastapi import FastAPI, Request app = FastAPI() # Anti-pattern: Unsynchronized global state mutated concurrently in GIL-less Python 3.13 request_metrics = {"active_requests": 0} current_tenant = None @app.middleware("http") async def trace_tenant(request: Request, call_next): global current_tenant # Race condition: Overwrites tenant context across concurrent OS threads current_tenant = request.headers.get("X-Tenant-ID", "default") # Race condition: Non-atomic in-place dictionary modification request_metrics["active_requests"] += 1 try: return await call_next(request) finally: request_metrics["active_requests"] -= 1 ``` #### Production Standard (Correct) > **Standard**: Uses `contextvars.ContextVar` to guarantee request context isolation across concurrent thread executions, eliminating cross-tenant leakage. Encapsulates mutable shared state within a synchronized class protected by `threading.Lock`, ensuring thread-safe reads and writes under free-threaded Python 3.13. ```python from contextvars import ContextVar from threading import Lock from dataclasses import dataclass from fastapi import FastAPI, Request, Response app = FastAPI() # Immutable request context isolation tenant_context: ContextVar[str] = ContextVar("tenant_context", default="default") @dataclass class ThreadSafeMetrics: _lock: Lock = Lock() _active_requests: int = 0 def increment(self) -> int: with self._lock: self._active_requests += 1 return self._active_requests def decrement(self) -> int: with self._lock: self._active_requests -= 1 return self._active_requests metrics = ThreadSafeMetrics() @app.middleware("http") async def trace_tenant(request: Request, call_next) -> Response: # Isolated context copy per async task / thread execution frame tenant_token = tenant_context.set(request.headers.get("X-Tenant-ID", "default")) metrics.increment() try: return await call_next(request) finally: metrics.decrement() tenant_context.reset(tenant_token) ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Free-Threaded Python 3.13 Concurrency Isolation and Safe Shared Memory Standard

Free-Threaded Python 3.13 Concurrency Isolation and Safe Shared Memory Standard defines an industrial-grade behavioral standard for backend engineering. Enforces strict thread-safe request context isolation and synchronization primitives for FastAPI microservices running under free-threaded Python 3.13 (PEP 703). Prevents data races, torn reads, and cross-thread memory corruption caused by concurrent mutations to unsynchronized module-level state, standard collections, and shared object pools. 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: Unsynchronized Global State Mutation and Context Bleed Under Free-Threaded Execution 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	Unsynchronized Global State Mutation and Context Bleed Under Free-Threaded Execution	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 isolate request-scoped state using `contextvars.ContextVar` instead of module-level variables or threading.local across async thread pools.

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.