fix(v2): make ModeRegistry.get_handlers() thread-safe with double-checked locking

[nexiouscaliver]

Summary

Fixes the thread-safety race condition in ModeRegistry.get_handlers() reported in #2422.

Concurrent first-access to a lazy-loaded (provider, mode) pair caused 49/50 threads to fail with KeyError/RegistryError because the winning thread popped the lazy loader entry from _lazy_loaders before the others could use it. Losing threads found the key absent from both _handlers and _lazy_loaders with no retry path.

Root Cause

The check → pop → import → set sequence in get_handlers() operated on shared module-level dicts with no synchronization:

# RACY: no lock
if mode_key in self._lazy_loaders:
    loader = self._lazy_loaders.pop(mode_key)   # ← gone for other threads
    handlers = loader()                          # ← slow import
    self._handlers[mode_key] = handlers          # ← set only after import returns
    return handlers
raise KeyError(...)                               # ← every concurrent loser lands here

Fix

Added threading.Lock to ModeRegistry with double-checked locking:

• Fast path (no lock): _handlers dict read — safe under the GIL for lookups, and once a handler is cached it is never removed
• Slow path (locked): _lock protects the entire pop → loader() → set sequence so concurrent callers serialize on the same in-flight load
• Also synchronized register() and register_lazy() since they mutate the same shared dicts

Verification

New regression test in tests/core/test_registry_thread_safety.py:

• test_concurrent_first_access_no_failures: 50 threads via ThreadPoolExecutor(max_workers=10) hit the same lazy-loaded mode simultaneously. Before fix: 49/50 fail. After fix: 0/50 fail.
• test_loader_called_exactly_once: Confirms the lock serializes lazy loading — loader is invoked exactly once even under heavy concurrency.
• test_double_checked_locking_resolves_quickly: Verifies fast path after first resolution.
• test_unregistered_mode_still_raises: Ensures KeyError is still raised for genuinely unregistered modes.
• test_concurrent_different_modes: Concurrent access to different keys does not interfere.

$ pytest tests/core/test_registry_thread_safety.py -v
5 passed in 0.67s

Files Changed

• instructor/v2/core/registry.py — added threading.Lock, double-checked locking in get_handlers(), synchronized register() and register_lazy()
• tests/core/test_registry_thread_safety.py — new regression tests
• CHANGELOG.md — entry under [Unreleased]

Closes #2422

[nexiouscaliver]

Hey @jxnl @ivanleomk — this fixes the thread-safety race condition in ModeRegistry.get_handlers() reported in #2422. The bug causes ~49/50 concurrent threads to permanently fail with KeyError on first lazy-load of any (provider, mode) pair. Would appreciate a review when you get a chance!

TL;DR: The check → pop → import → set sequence in get_handlers() had no lock. Added double-checked locking with threading.Lock. Includes regression tests that reproduce the 49/50 failure before the fix and 0/50 after.

[nexiouscaliver]

Friendly nudge! Just pushed a cleanup commit fixing ruff lint/format in the test file. CI workflows need maintainer approval to run on fork PRs — could someone approve? 5/5 tests pass, ruff clean. @jxnl @ivanleomk

[jxnl]

Superseded by #2495, which uses a lazy-load-specific lock and avoids coupling registration to loader resolution.