fix: address review — docs consistency, channel tests, random.choices

- DECISIONS.md: rename "Why Global Singleton on Chat" to "Why 3-Level
  Chat Resolver" with updated rationale reflecting the actual design
- Add 7 ChannelImpl resolver tests (symmetric with ThreadImpl coverage):
  explicit chat=, activate(), beats global, concurrent isolation
- Add 2 reviver channel tests (deserialize + bound to specific chat)
- Comment random.choices in GChat _random_id() as cosmetic-only, not
  suitable for security purposes

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: patrick-chinchill

docs/DECISIONS.md

@@ -50,19 +50,23 @@ The tradeoff is that we must maintain the JWKS fetching and JWT validation code
 
 5. **Not classes**: The builders are functions that return TypedDicts, not class constructors. Using PascalCase for class constructors is standard Python. Using it for factory functions is a deliberate style choice for this domain.
 
-## Why Global Singleton on Chat
+## Why 3-Level Chat Resolver
 
-**Decision**: `Chat` registers itself as a global singleton via `set_chat_singleton(self)`. Thread and Channel deserialization uses `get_chat_singleton()` to resolve adapters.
+**Decision**: Thread and Channel deserialization resolves the active Chat instance through a 3-level chain: explicit `chat=` parameter → `ContextVar` → process-global fallback.
 
 **Rationale**:
 
-1. **Deserialization without context**: When a `ThreadImpl` is deserialized from JSON (e.g., from Redis state, from a queued entry, from modal context), it needs to resolve its adapter by name. Without a singleton, every deserialization call would need an explicit `chat` parameter threaded through the call stack.
+1. **Explicit is best**: `ThreadImpl.from_json(data, chat=chat)` is unambiguous and needs no ambient state. Preferred for library code and multi-tenant servers.
 
-2. **Matches TS SDK**: The TS SDK uses `chat-singleton.ts` with the same pattern. Keeping the pattern identical reduces the cognitive load of syncing changes.
+2. **ContextVar for async isolation**: `chat.activate()` sets a task-local `ContextVar`. Concurrent async tasks can each have their own Chat without interference. This is the natural Python pattern for request-scoped state (same approach the Slack adapter uses for per-request auth context).
 
-3. **Single Chat instance is the normal case**: In practice, applications have exactly one `Chat` instance. The singleton is registered during initialization and remains for the lifetime of the process.
+3. **Global fallback for simplicity**: `chat.register_singleton()` sets a process-global default. This is the TS SDK's pattern and works for the common single-Chat-per-process case. Existing code using `register_singleton()` is unchanged.
 
-4. **Testing escape hatch**: `clear_chat_singleton()` and `has_chat_singleton()` are provided for test isolation. Each test can register its own singleton.
+4. **Resolution order**: `get_chat_singleton()` checks ContextVar first, then global, then raises `RuntimeError`. This means `activate()` always wins over the global, and explicit `chat=` always wins over both.
+
+5. **Testing isolation**: Each test can use `with chat.activate():` or pass `chat=` explicitly instead of fighting over a single global. `clear_chat_singleton()` is still available for cleanup.
+
+6. **Upstream sync cost is low**: The TS SDK uses a pure global. The Python resolver is a strict superset — `register_singleton()` and `get_chat_singleton()` still exist and behave identically for single-Chat usage. Upstream ports that touch deserialization paths work without modification.
 
 ## Why Zero Runtime Dependencies in Core
 

src/chat_sdk/adapters/google_chat/adapter.py

@@ -2709,7 +2709,13 @@ def __init__(
 
 
 def _random_id() -> str:
-    """Generate a short random ID similar to Math.random().toString(36).slice(2, 9)."""
+    """Generate a short random ID for cosmetic use (card widget IDs).
+
+    NOT suitable for security-sensitive purposes (lock tokens, signatures, etc.)
+    — use ``secrets.token_hex()`` for those. This uses ``random.choices`` because
+    these IDs are only used as opaque Google Chat card widget suffixes and do not
+    need to be unpredictable.
+    """
     import random
     import string
 

tests/test_chat_resolver.py

@@ -15,6 +15,7 @@
 import pytest
 
 from chat_sdk import Chat, MemoryStateAdapter
+from chat_sdk.channel import ChannelImpl
 from chat_sdk.testing import create_mock_adapter
 from chat_sdk.thread import (
     ThreadImpl,
@@ -41,6 +42,16 @@ def _thread_json(adapter_name: str = "slack") -> dict:
     }
 
 
+def _channel_json(adapter_name: str = "slack") -> dict:
+    return {
+        "_type": "chat:Channel",
+        "id": f"{adapter_name}:C1",
+        "channelVisibility": "public",
+        "isDM": False,
+        "adapterName": adapter_name,
+    }
+
+
 class TestGlobalSingleton:
     """Existing register_singleton pattern still works."""
 
@@ -250,3 +261,74 @@ def test_reviver_passes_through_non_typed_values(self):
         assert reviver("key", "plain string") == "plain string"
         assert reviver("key", 42) == 42
         assert reviver("key", {"no_type": True}) == {"no_type": True}
+
+    def test_reviver_deserializes_channel(self):
+        chat = _make_chat("slack")
+        reviver = chat.reviver()
+        data = _channel_json("slack")
+        channel = reviver("key", data)
+        assert isinstance(channel, ChannelImpl)
+        assert channel.adapter.name == "slack"
+
+    def test_reviver_channel_bound_to_specific_chat(self):
+        chat_a = _make_chat("a")
+        chat_b = _make_chat("b")
+
+        reviver_a = chat_a.reviver()
+        reviver_b = chat_b.reviver()
+
+        ch_a = reviver_a("k", _channel_json("a"))
+        ch_b = reviver_b("k", _channel_json("b"))
+
+        assert ch_a.adapter.name == "a"
+        assert ch_b.adapter.name == "b"
+
+
+class TestChannelImplResolver:
+    """Symmetric ChannelImpl coverage for the 3-level resolver."""
+
+    def setup_method(self):
+        clear_chat_singleton()
+
+    def teardown_method(self):
+        clear_chat_singleton()
+
+    def test_explicit_chat_parameter(self):
+        chat = _make_chat("slack")
+        data = _channel_json("slack")
+        channel = ChannelImpl.from_json(data, chat=chat)
+        assert channel.adapter.name == "slack"
+
+    def test_explicit_chat_beats_global(self):
+        global_chat = _make_chat("global")
+        explicit_chat = _make_chat("explicit")
+        global_chat.register_singleton()
+
+        channel = ChannelImpl.from_json(_channel_json("explicit"), chat=explicit_chat)
+        assert channel.adapter.name == "explicit"
+
+    def test_activate_resolves_channel(self):
+        chat = _make_chat("slack")
+        with chat.activate():
+            channel = ChannelImpl.from_json(_channel_json("slack"))
+            assert channel.adapter.name == "slack"
+
+    def test_explicit_chat_without_singleton(self):
+        chat = _make_chat("solo")
+        channel = ChannelImpl.from_json(_channel_json("solo"), chat=chat)
+        assert channel.adapter.name == "solo"
+
+    async def test_concurrent_channel_isolation(self):
+        chat_a = _make_chat("ca")
+        chat_b = _make_chat("cb")
+        results: dict[str, str] = {}
+
+        async def task(chat: Chat, name: str) -> None:
+            with chat.activate():
+                await asyncio.sleep(0.01)
+                channel = ChannelImpl.from_json(_channel_json(name))
+                results[name] = channel.adapter.name
+
+        await asyncio.gather(task(chat_a, "ca"), task(chat_b, "cb"))
+        assert results["ca"] == "ca"
+        assert results["cb"] == "cb"