feat: Protocol interfaces + TypedDict schemas for target architecture (#496)

[ShaerWare]

Summary

• Define target Protocol interfaces for 4 domains: KnowledgeService, LLMService, ChatService, AuthService
• Define ideal TypedDict response schemas: SearchResult, SessionInfo, MessageInfo, ProviderInfo, UserInfo, LoginResult, etc.
• Protocols describe the architectural north star — current implementations do not yet conform
• TypedDicts are backward-compatible with dict (minimal blast radius for future adoption)
• 28 unit tests verify schema construction and protocol method signatures

Structure

modules/{domain}/schemas.py    ← TypedDict response types
modules/{domain}/protocols.py  ← Protocol service contracts

Domain	Protocol	Key methods
Knowledge	KnowledgeService	search, retrieve_context, get_collections, sync_documents, find_faq_answer
LLM	LLMService	generate, stream, resolve_backend, list_providers
Chat	ChatService	create_session, send_message, stream_message, get_history, share_session
Auth	AuthService	authenticate, validate_token, get_permissions, has_permission, get_roles

Design decisions

• Ideal, not current: Protocols describe what should be, not wrapping current fragmented services
• TypedDict over dataclass: backward-compatible with dict — existing session["id"] code works unchanged
• runtime_checkable: enables isinstance() checks for future DI validation
• No DI changes: Protocols are purely additive — no service wiring changes
• TCH suppressed in tests: test files need runtime imports for schema construction

Test plan

• 28 new tests pass (pytest tests/unit/test_protocols.py)
• All 134 unit tests pass (no regressions)
• CI checks (lint-backend, lint-frontend, security)

Closes #496

🤖 Generated with Claude Code