Add comprehensive borrow checker specification for thread-safe ownership

[andreisavu]

Summary

This PR introduces a comprehensive specification document for a Rust-inspired borrow checker implementation in Python. The specification defines a complete system for enforcing thread-safe ownership and borrowing semantics at runtime, addressing concurrency challenges in the codebase.

Key Changes

• Core API Design: Defines Owned[T] for single ownership, SharedRef[T] for shared references with interior mutability, WeakRef[T] for non-owning references, and ThreadLocal[T] for thread-isolated storage
• Borrow Rules: Specifies runtime enforcement of Rust's borrowing model - multiple immutable borrows OR one mutable borrow, but never both simultaneously
• Thread Context Tracking: Details per-thread context registry for tracking active borrows and owned values with automatic cleanup on thread exit
• Codebase Integration: Provides concrete examples showing how to apply the borrow checker to 7 specific patterns in the codebase:
  • Shared Redis client in mailboxes.py
  • Shared adapter in agent_loop.py
  • Prompt overrides store
  • Per-request session isolation
  • LoopGroup concurrent execution
  • Debug bundle directory access
  • Message queue polling in dispatch.py
• Implementation Details: Includes pseudocode for thread context registry, Owned implementation with condition variables, and SharedRef with reader-writer locking
• Error Handling: Defines exception hierarchy (BorrowError, OwnershipError, UseAfterMoveError, DeadlockDetectedError) with detailed error messages
• Performance Analysis: Documents overhead (~0.3-1μs per operation) and optimization strategies for high-frequency access patterns
• Future Extensions: Sketches async support, type checker integration, and observability features

Notable Implementation Details

• Uses threading.RLock and threading.Condition for synchronization
• Implements reader-writer locking in SharedRef to prevent writer starvation
• Provides both blocking (borrow(), borrow_mut()) and non-blocking (try_borrow(), try_borrow_mut()) APIs
• Includes debug mode support for detailed tracking and deadlock detection
• Weak reference support via WeakRef for breaking circular ownership chains
• Send and Sync marker types for asserting thread-safety properties

This specification provides the foundation for implementing a production-ready borrow checker that prevents data races, use-after-free bugs, and unclear ownership patterns throughout the codebase.

https://claude.ai/code/session_013gpdCop4MxVmfD68WA8fN8