ltcai 8.9.0 → 9.1.0

package/latticeai/app_factory.py

@@ -18,7 +18,6 @@ import threading
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, Dict, List, Optional
 
-from latticeai.runtime.app_context_runtime import build_app_context
 from latticeai.runtime.access_runtime import build_access_runtime
 from latticeai.runtime.bootstrap import build_session_runtime
 from latticeai.runtime.brain_runtime import build_brain_runtime
@@ -34,21 +33,25 @@ from latticeai.runtime.hooks_runtime import (
     bind_trigger_hook_runner,
     build_hooks_runtime,
 )
+from latticeai.runtime.history_runtime import build_history_query_runtime
 from latticeai.runtime.lifespan_runtime import build_lifespan_runtime
+from latticeai.runtime.network_config_runtime import build_vpc_runtime
 from latticeai.runtime.model_wiring import (
     configure_model_runtime_from_context,
     register_model_runtime_routers,
 )
+from latticeai.runtime.namespace_runtime import RuntimeBundle, build_runtime_namespace
 from latticeai.runtime.platform_services_runtime import (
     build_brain_network,
 )
 from latticeai.runtime.platform_runtime_wiring import build_platform_automation_runtime
 from latticeai.runtime.persistence_runtime import build_persistence_runtime
 from latticeai.runtime.review_wiring import build_review_run_now_runner
-from latticeai.runtime.sso_runtime import build_sso_runtime
+from latticeai.runtime.sso_config_runtime import build_sso_config_runtime
 from latticeai.runtime.audit_runtime import build_audit_runtime
 from latticeai.runtime.router_registration import (
     build_auth_admin_security_router_bundle,
+    build_router_bundle,
     build_static_routes_bundle,
     register_health_and_model_routers,
     register_foundation_routers,
@@ -57,7 +60,7 @@ from latticeai.runtime.router_registration import (
     register_review_and_brain_tail_routers,
 )
 from latticeai.runtime.security_runtime import build_security_runtime
-from latticeai.runtime.tail_wiring import register_tail_runtime_routers
+from latticeai.runtime.user_key_runtime import build_user_key_runtime
 from latticeai.runtime.web_runtime import build_web_runtime
 
 if TYPE_CHECKING:  # imports for annotations only — keep module import light
@@ -73,14 +76,9 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
     deliberately *inside* this function so that importing the module performs
     no GPU init, no singleton construction, and no filesystem writes.
     """
-    import hashlib
-    import json
     import logging
     import os
-    import re
-    import secrets
     import threading
-    import time
     from pathlib import Path
 
     try:
@@ -108,7 +106,7 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
         enforce_rate_limit as _enforce_rate_limit,
     )
     from latticeai.core.audit import (
-        get_audit_log as _get_audit_log,  # noqa: F401 - legacy server_app attr exported via locals()
+        get_audit_log as _get_audit_log,  # noqa: F401 - explicit legacy server_app export
         classify_sensitive_message as _classify_sensitive_message,
         build_sensitivity_report as _build_sensitivity_report,
         build_admin_audit_report as _build_admin_audit_report,
@@ -133,24 +131,19 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
         user_id_for_email as _user_id_for_email,
     )
     from latticeai.services.chat_service import ChatService
+    from latticeai.services.app_context import AppContext
     from latticeai.core.embedding_providers import resolve_embedder, resolve_embedding_profile
     from latticeai.services.model_runtime import (
         CLOUD_VERIFY_TTL_SECONDS,
         ENGINE_MODEL_CATALOG,
         LOCAL_SERVER_PROCESSES,
         MODEL_ENGINE_ALIASES,
-        configure_model_runtime,
+        build_model_runtime,
         download_hf_model,
-        engine_status,
         filter_lower_family_versions,
-        install_engine,
         local_binary,
         normalize_local_model_request,
-        prepare_and_load_model,
-        prepare_and_load_model_stream,
-        runtime_features,
         sse_event,
-        verify_cloud_models,
         ensure_ollama_server,
     )
     from latticeai.api.workspace import create_workspace_router, _workspace_scope_from_request
@@ -178,10 +171,8 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
     from lattice_brain.ingestion import IngestionItem
     from lattice_brain.storage import storage_from_env
     from latticeai.api.network import create_network_router
-    # The aliased names below look unused but are part of the legacy
-    # ``server_app`` attribute surface: every local is exported via
-    # ``dict(locals())`` and reached through ``server_app.__getattr__``
-    # (tests import _agent_risk, _LOCAL_WRITE_BLOCKED_PREFIXES, …).
+    # The aliased names below form the explicit, allowlisted compatibility
+    # surface consumed by historical ``server_app`` callers.
     from latticeai.services.tool_dispatch import (  # noqa: F401
         LOCAL_WRITE_BLOCKED_PREFIXES as _LOCAL_WRITE_BLOCKED_PREFIXES,
         TOOL_GOVERNANCE,
@@ -202,8 +193,8 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
         create_mcp_install_state,
     )
     from latticeai.services.p_reinforce import PReinforceGardener
-    from setup_wizard import get_recommendations, scan_environment
-    from tools import ensure_agent_root, execute_tool, knowledge_save
+    from latticeai.setup.wizard import get_recommendations, scan_environment
+    from latticeai.tools import ensure_agent_root, execute_tool, knowledge_save
 
     try:
         import keyring
@@ -230,7 +221,6 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
     def _host_is_loopback(host: str) -> bool:
         return _host_is_loopback_impl(host)
 
-    NETWORK_EXPOSED = _config_runtime["NETWORK_EXPOSED"]
     ENABLE_TELEGRAM = _config_runtime["ENABLE_TELEGRAM"]
     ENABLE_GRAPH    = _config_runtime["ENABLE_GRAPH"]
     AUTOLOAD_MODELS = _config_runtime["AUTOLOAD_MODELS"]
@@ -254,12 +244,13 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
     SSO_CLIENT_SECRET = _security_runtime["SSO_CLIENT_SECRET"]
     SSO_REDIRECT_URI = _security_runtime["SSO_REDIRECT_URI"]
     SSO_PROVIDER_NAME = _security_runtime["SSO_PROVIDER_NAME"]
+    INVITE_CODE = _security_runtime["INVITE_CODE"]
+    INVITE_COOKIE_SECRET = _security_runtime["INVITE_COOKIE_SECRET"]
+    INVITE_GATE_ENABLED = _security_runtime["INVITE_GATE_ENABLED"]
+    SECURE_COOKIES = _security_runtime["SECURE_COOKIES"]
 
-    # SSO cache + discovery built after get_sso_settings is defined (see below)
-    _sso_discovery_cache = None
-    _sso_discovery_cache_url = ""
-    _sso_states: Dict[str, float] = {}
-    _get_sso_discovery = None  # filled after def below
+    # SSO config + discovery seam is built below, after SSO_FILE is known
+    # (latticeai.runtime.sso_config_runtime).
 
     # ── Password hashing — used directly from latticeai.core.security ──────────────
     # (hash_password / verify_password are imported above; no local wrapper needed)
@@ -295,26 +286,27 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
     _session_store = _session_runtime["_session_store"]
     create_session = _session_runtime["create_session"]
     get_session_email = _session_runtime["get_session_email"]
-    get_session_user_id = _session_runtime["get_session_user_id"]
     invalidate_session = _session_runtime["invalidate_session"]
 
     # ── User Management Logic ──────────────────────────────────────────────────
     BASE_DIR = Path(__file__).resolve().parent.parent
     DATA_DIR = CONFIG.data_dir
-    DATA_DIR.mkdir(parents=True, exist_ok=True)
+    DATA_DIR.mkdir(parents=True, exist_ok=True, mode=0o700)
+    try:
+        DATA_DIR.chmod(0o700)
+    except OSError:
+        pass
     STATIC_DIR = CONFIG.static_dir
 
     USERS_FILE = DATA_DIR / "users.json"
     HISTORY_FILE = DATA_DIR / "chat_history.json"
     VPC_FILE = DATA_DIR / "vpc_config.json"
-    MCP_FILE = DATA_DIR / "mcp_installs.json"
     AUDIT_FILE = DATA_DIR / "audit_log.json"
     SSO_FILE = DATA_DIR / "sso_config.json"
 
     # MCP state extracted to mcp_registry.create_mcp_install_state (server decomp)
     _mcp_state = create_mcp_install_state(DATA_DIR)
     load_mcp_installs = _mcp_state["load_mcp_installs"]
-    save_mcp_installs = _mcp_state["save_mcp_installs"]
     mcp_public_item = _mcp_state["mcp_public_item"]
     recommend_mcps = _mcp_state["recommend_mcps"]
     install_mcp = _mcp_state["install_mcp"]
@@ -354,7 +346,6 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
         embedder=EMBEDDER,
         storage_engine=STORAGE_ENGINE,
     )
-    BRAIN_CORE = _brain_runtime["BRAIN_CORE"]
     KNOWLEDGE_GRAPH = _brain_runtime["KNOWLEDGE_GRAPH"]
     # ── v4 durable conversation store: unbounded episodic memory in the same
     # SQLite file as the graph (kg_portability backup/restore covers it for
@@ -388,7 +379,6 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
     WORKSPACE_OS = _persistence_runtime["WORKSPACE_OS"]
     WORKSPACE_SERVICE = _persistence_runtime["WORKSPACE_SERVICE"]
     INVITATION_STORE = _persistence_runtime["INVITATION_STORE"]
-    PLUGINS_DIR = _persistence_runtime["PLUGINS_DIR"]
     PLUGIN_REGISTRY = _persistence_runtime["PLUGIN_REGISTRY"]
     TEMPLATE_CATALOG = _persistence_runtime["TEMPLATE_CATALOG"]
     AGENT_REGISTRY = _persistence_runtime["AGENT_REGISTRY"]
@@ -434,89 +424,29 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
         redirect_uri: Optional[str] = None
         scopes: Optional[str] = None
 
-    def _sso_env_defaults() -> Dict[str, object]:
-        return {
-            "enabled": bool(SSO_DISCOVERY_URL and SSO_CLIENT_ID and SSO_CLIENT_SECRET),
-            "provider_name": SSO_PROVIDER_NAME,
-            "discovery_url": SSO_DISCOVERY_URL,
-            "client_id": SSO_CLIENT_ID,
-            "client_secret": SSO_CLIENT_SECRET,
-            "redirect_uri": SSO_REDIRECT_URI,
-            "scopes": "openid email profile",
-        }
-
-    def load_sso_config() -> Dict[str, object]:
-        config = _sso_env_defaults()
-        if SSO_FILE.exists():
-            try:
-                data = json.loads(SSO_FILE.read_text(encoding="utf-8"))
-                if isinstance(data, dict):
-                    config.update({k: v for k, v in data.items() if v is not None})
-            except Exception as e:
-                logging.warning("load_sso_config failed (using env/defaults): %s", e)
-        config["provider_name"] = str(config.get("provider_name") or "SSO")
-        config["discovery_url"] = str(config.get("discovery_url") or "")
-        config["client_id"] = str(config.get("client_id") or "")
-        config["client_secret"] = str(config.get("client_secret") or "")
-        config["redirect_uri"] = str(config.get("redirect_uri") or SSO_REDIRECT_URI)
-        config["scopes"] = str(config.get("scopes") or "openid email profile")
-        config["enabled"] = bool(config.get("enabled")) and bool(
-            config["discovery_url"] and config["client_id"] and config["client_secret"]
-        )
-        return config
-
-    def get_sso_settings() -> Dict[str, object]:
-        return load_sso_config()
-
-    # Build SSO runtime (cache + helper) now that get_sso_settings exists in scope.
-    if _get_sso_discovery is None:
-        _sso = build_sso_runtime(
-            get_sso_settings=get_sso_settings,
-            logging=logging,
-        )
-        _sso_discovery_cache = _sso["_sso_discovery_cache"]
-        _sso_discovery_cache_url = _sso["_sso_discovery_cache_url"]
-        _sso_states = _sso["_sso_states"]
-        _get_sso_discovery = _sso["_get_sso_discovery"]
-
-    def public_sso_config(config: Optional[Dict[str, object]] = None) -> Dict[str, object]:
-        cfg = config or get_sso_settings()
-        return {
-            "enabled": bool(cfg.get("enabled")),
-            "provider_name": cfg.get("provider_name") or "",
-            "discovery_url": cfg.get("discovery_url") or "",
-            "client_id": cfg.get("client_id") or "",
-            "redirect_uri": cfg.get("redirect_uri") or SSO_REDIRECT_URI,
-            "scopes": cfg.get("scopes") or "openid email profile",
-            "secret_configured": bool(cfg.get("client_secret")),
-        }
-
-    def save_sso_config(update: Dict[str, object]) -> Dict[str, object]:
-        nonlocal _sso_discovery_cache, _sso_discovery_cache_url
-        current = load_sso_config()
-        if update.get("client_secret") == "":
-            update.pop("client_secret", None)
-        current.update({k: v for k, v in update.items() if v is not None})
-        current["enabled"] = bool(current.get("enabled")) and bool(
-            current.get("discovery_url") and current.get("client_id") and current.get("client_secret")
-        )
-        SSO_FILE.write_text(json.dumps(current, ensure_ascii=False, indent=2), encoding="utf-8")
-        _sso_discovery_cache = None
-        _sso_discovery_cache_url = ""
-        return current
+    # SSO config + OIDC discovery seam. One closure owns config load/save and the
+    # discovery cache, so save_sso_config now actually invalidates discovery.
+    _sso_runtime = build_sso_config_runtime(
+        sso_file=SSO_FILE,
+        discovery_url=SSO_DISCOVERY_URL,
+        client_id=SSO_CLIENT_ID,
+        client_secret=SSO_CLIENT_SECRET,
+        redirect_uri=SSO_REDIRECT_URI,
+        provider_name=SSO_PROVIDER_NAME,
+        logging=logging,
+    )
+    _sso_env_defaults = _sso_runtime["_sso_env_defaults"]
+    get_sso_settings = _sso_runtime["get_sso_settings"]
+    public_sso_config = _sso_runtime["public_sso_config"]
+    save_sso_config = _sso_runtime["save_sso_config"]
+    _get_sso_discovery = _sso_runtime["_get_sso_discovery"]
+    _sso_states = _sso_runtime["_sso_states"]
 
     # MCP/skill request models moved to latticeai.api.mcp (v1.3.0).
-    DEFAULT_VPC_CONFIG = {
-        "provider": "AWS",
-        "region": "ap-northeast-2",
-        "cidr_block": "10.42.0.0/16",
-        "private_subnets": ["10.42.10.0/24", "10.42.20.0/24"],
-        "endpoint": "ltcai-private.local",
-        "vpn_status": "standby",
-        "peering_status": "not_configured",
-        "notes": "로컬 MLX 브릿지를 프라이빗 서브넷 또는 VPN 뒤에서 운영할 때 쓰는 네트워크 프로필입니다.",
-        "updated_at": None,
-    }
+    # VPC network-profile config → latticeai.runtime.network_config_runtime.
+    _vpc_runtime = build_vpc_runtime(vpc_file=VPC_FILE, logging=logging)
+    load_vpc_config = _vpc_runtime["load_vpc_config"]
+    save_vpc_config = _vpc_runtime["save_vpc_config"]
 
 
     def load_users():
@@ -539,22 +469,6 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
     def save_users(users):
         save_users_file(USERS_FILE, users)
 
-    def load_vpc_config() -> Dict:
-        if not os.path.exists(VPC_FILE):
-            return DEFAULT_VPC_CONFIG.copy()
-        try:
-            with open(VPC_FILE, "r", encoding="utf-8") as f:
-                stored = json.load(f)
-            return {**DEFAULT_VPC_CONFIG, **stored}
-        except Exception as e:
-            logging.warning("load_vpc_config failed (using defaults): %s", e)
-            return DEFAULT_VPC_CONFIG.copy()
-
-    def save_vpc_config(config: Dict):
-        config["updated_at"] = datetime.now().isoformat()
-        with open(VPC_FILE, "w", encoding="utf-8") as f:
-            json.dump(config, f, ensure_ascii=False, indent=2)
-
 
     _history_lock = threading.Lock()
 
@@ -639,130 +553,23 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
     get_audit_log = _audit_rt["get_audit_log"]
     append_audit_event = _audit_rt["append_audit_event"]
 
-    def _history_allowed_workspaces_for(user_email: Optional[str]):
-        if not REQUIRE_AUTH or not user_email:
-            return None
-        try:
-            return set(WORKSPACE_SERVICE.readable_workspaces(user_email))
-        except Exception as exc:
-            logging.warning("history workspace scope resolution failed for %s: %s", user_email, exc)
-            return set()
-
-    def _history_include_legacy_global(user_email: Optional[str]) -> bool:
-        return not REQUIRE_AUTH or not user_email
-
-    def get_history(
-        user_email: Optional[str] = None,
-        allowed_workspaces=None,
-        include_legacy_global: Optional[bool] = None,
-    ):
-        try:
-            if allowed_workspaces is None and user_email:
-                allowed_workspaces = _history_allowed_workspaces_for(user_email)
-            if include_legacy_global is None:
-                include_legacy_global = _history_include_legacy_global(user_email)
-            return CONVERSATIONS.history(
-                user_email=user_email,
-                allowed_workspaces=allowed_workspaces,
-                include_legacy_global=include_legacy_global,
-            )
-        except Exception as e:
-            logging.warning("get_history failed: %s", e)
-            return []
-
-    # Chat service seam: behaviour-preserving façade for history access and
-    # Workspace-OS answer-trace recording used by the (unchanged) streaming chat path.
-    CHAT_SERVICE = ChatService(store=WORKSPACE_OS, get_history=get_history)
-
-    def conversation_title(item: Dict) -> str:
-        content = str(item.get("content") or "").strip()
-        content = re.sub(r"\s+", " ", content)
-        return content[:48] or "새 대화"
-
-    def group_history_conversations(history: Optional[List[Dict]] = None) -> List[Dict]:
-        history = history if history is not None else get_history()
-        conversations: Dict[str, Dict] = {}
-        order: List[str] = []
-
-        for index, item in enumerate(history):
-            conv_id = item.get("conversation_id")
-            if not conv_id:
-                conv_id = "legacy-previous-history"
-
-            if conv_id not in conversations:
-                conversations[conv_id] = {
-                    "id": conv_id,
-                    "title": "이전 대화 기록" if conv_id == "legacy-previous-history" else conversation_title(item),
-                    "created_at": item.get("timestamp"),
-                    "updated_at": item.get("timestamp"),
-                    "message_count": 0,
-                    "last_message": "",
-                    "source": item.get("source"),
-                }
-                order.append(conv_id)
-
-            conv = conversations[conv_id]
-            conv["message_count"] += 1
-            conv["updated_at"] = item.get("timestamp") or conv.get("updated_at")
-            conv["last_message"] = conversation_title(item)
-            if conv_id != "legacy-previous-history" and item.get("role") == "user" and (not conv.get("title") or conv["title"] == "새 대화"):
-                conv["title"] = conversation_title(item)
-
-        return sorted((conversations[key] for key in order), key=lambda item: item.get("updated_at") or "", reverse=True)
-
-    def get_conversation_messages(
-        conversation_id: str,
-        *,
-        user_email: Optional[str] = None,
-        allowed_workspaces=None,
-        include_legacy_global: Optional[bool] = None,
-    ) -> List[Dict]:
-        history = get_history(
-            user_email=user_email,
-            allowed_workspaces=allowed_workspaces,
-            include_legacy_global=include_legacy_global,
-        )
-        if conversation_id == "legacy-previous-history":
-            return [item for item in history if not item.get("conversation_id")]
-        return [item for item in history if item.get("conversation_id") == conversation_id]
-
-    def clear_history(
-        keep_last: int = 0,
-        *,
-        user_email: Optional[str] = None,
-        allowed_workspaces=None,
-        include_legacy_global: Optional[bool] = None,
-    ) -> Dict:
-        if allowed_workspaces is None and user_email:
-            allowed_workspaces = _history_allowed_workspaces_for(user_email)
-        if include_legacy_global is None:
-            include_legacy_global = _history_include_legacy_global(user_email)
-        return CONVERSATIONS.clear_all(
-            keep_last=keep_last,
-            user_email=user_email,
-            allowed_workspaces=allowed_workspaces,
-            include_legacy_global=include_legacy_global,
-        )
-
-    def clear_conversation(
-        conversation_id: str,
-        started_at: Optional[str] = None,
-        *,
-        user_email: Optional[str] = None,
-        allowed_workspaces=None,
-        include_legacy_global: Optional[bool] = None,
-    ) -> Dict:
-        if allowed_workspaces is None and user_email:
-            allowed_workspaces = _history_allowed_workspaces_for(user_email)
-        if include_legacy_global is None:
-            include_legacy_global = _history_include_legacy_global(user_email)
-        return CONVERSATIONS.clear_conversation(
-            conversation_id,
-            started_at=started_at,
-            user_email=user_email,
-            allowed_workspaces=allowed_workspaces,
-            include_legacy_global=include_legacy_global,
-        )
+    # History query/clear seam (scope resolution, get_history, grouping, clears)
+    # → latticeai.runtime.history_runtime. save_to_history (the write path) stays
+    # inline above because it is bound to redaction/audit/ingestion.
+    _history_query_runtime = build_history_query_runtime(
+        conversations=CONVERSATIONS,
+        workspace_service=WORKSPACE_SERVICE,
+        require_auth=REQUIRE_AUTH,
+        logging=logging,
+    )
+    _history_allowed_workspaces_for = _history_query_runtime["_history_allowed_workspaces_for"]
+    _history_include_legacy_global = _history_query_runtime["_history_include_legacy_global"]
+    get_history = _history_query_runtime["get_history"]
+    conversation_title = _history_query_runtime["conversation_title"]
+    group_history_conversations = _history_query_runtime["group_history_conversations"]
+    get_conversation_messages = _history_query_runtime["get_conversation_messages"]
+    clear_history = _history_query_runtime["clear_history"]
+    clear_conversation = _history_query_runtime["clear_conversation"]
 
     _access_runtime = build_access_runtime(
         config=CONFIG,
@@ -790,136 +597,33 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
     def _bytes_match_extension(data: bytes, ext: str) -> bool:
         return _bytes_match_extension_impl(data, ext)
 
-    _LOCAL_APPROVAL_TTL_SECONDS = 5 * 60
-    _local_approvals: Dict[str, Dict[str, object]] = {}
-
-
-    def _normalize_local_path_for_approval(path: str) -> str:
-        return str(Path(path).expanduser().resolve())
-
-
-    def _content_fingerprint(content: str = "") -> str:
-        return hashlib.sha256(content.encode("utf-8")).hexdigest()
-
-
-    def _local_permission_response(path: str, action: str, user_email: str, content: str = "") -> dict:
-        normalized = _normalize_local_path_for_approval(path)
-        token = secrets.token_urlsafe(24)
-        record: Dict[str, object] = {
-            "path": normalized,
-            "action": action,
-            "user_email": user_email,
-            "expires_at": time.time() + _LOCAL_APPROVAL_TTL_SECONDS,
-            "approved": False,
-        }
-        if action == "write":
-            record["content_hash"] = _content_fingerprint(content)
-        _local_approvals[token] = record
-        return {
-            "permission_required": True,
-            "path": path,
-            "action": action,
-            "approval_token": token,
-            "expires_in": _LOCAL_APPROVAL_TTL_SECONDS,
-        }
-
-
-    def _require_local_approval(
-        *,
-        token: Optional[str],
-        path: str,
-        action: str,
-        user_email: str,
-        content: str = "",
-    ) -> None:
-        if not token:
-            raise HTTPException(status_code=403, detail="파일 접근 승인 토큰이 필요합니다.")
-        record = _local_approvals.get(token)
-        if not record or float(record.get("expires_at", 0)) < time.time():
-            raise HTTPException(status_code=403, detail="파일 접근 승인이 만료되었거나 유효하지 않습니다.")
-        if not record.get("approved"):
-            raise HTTPException(status_code=403, detail="파일 접근이 아직 승인되지 않았습니다.")
-        if record.get("user_email") != user_email:
-            raise HTTPException(status_code=403, detail="다른 사용자의 파일 접근 승인은 사용할 수 없습니다.")
-        if record.get("path") != _normalize_local_path_for_approval(path) or record.get("action") != action:
-            raise HTTPException(status_code=403, detail="파일 접근 승인 범위가 일치하지 않습니다.")
-        if action == "write" and record.get("content_hash") != _content_fingerprint(content):
-            raise HTTPException(status_code=403, detail="승인된 파일 내용과 요청 내용이 다릅니다.")
-
-
-    def get_history_user(email: Optional[str], nickname: Optional[str] = None) -> Dict:
-        if not email:
-            return {"user_email": None, "user_nickname": nickname or None}
-        users = load_users()
-        user = users.get(email, {})
-        return {
-            "user_email": email,
-            "user_nickname": nickname or user.get("nickname") or user.get("name") or email,
-        }
+    # Local file-access approval lives entirely in
+    # ``latticeai.api.permissions.PermissionGateway`` (token hash-at-rest,
+    # persisted approval queue, Discord notifications). The historical inline
+    # copy that used to sit here was app-dead — no route referenced it — so it
+    # was removed to keep this factory a single wiring path.
 
-    def get_user_api_key(email: Optional[str], provider: str) -> Optional[str]:
-        if not email:
-            return None
-        keyring_key = f"{email}:{provider}"
-        if keyring is not None:
-            try:
-                key = keyring.get_password("LatticeAI", keyring_key)
-                if key:
-                    return key.strip()
-            except Exception as exc:
-                logging.warning("keyring read failed for %s: %s", provider, exc)
-        users = load_users()
-        user = users.get(email) or {}
-        api_keys = user.get("api_keys") or {}
-        key = api_keys.get(provider)
-        if isinstance(key, str) and key.strip() and ALLOW_PLAINTEXT_API_KEYS:
-            return key.strip()
-        return None
-
-    def set_user_api_key(email: str, provider: str, key: str) -> None:
-        keyring_key = f"{email}:{provider}"
-        if keyring is not None:
-            try:
-                keyring.set_password("LatticeAI", keyring_key, key)
-                users = load_users()
-                user = users.get(email)
-                if user and "api_keys" in user:
-                    user["api_keys"].pop(provider, None)
-                    if not user["api_keys"]:
-                        user.pop("api_keys", None)
-                    save_users(users)
-                return
-            except Exception as exc:
-                logging.warning("keyring write failed for %s: %s", provider, exc)
-                if not ALLOW_PLAINTEXT_API_KEYS:
-                    raise HTTPException(
-                        status_code=500,
-                        detail="OS keyring에 API 키를 저장하지 못했습니다. keyring 설정을 확인하거나 LATTICEAI_ALLOW_PLAINTEXT_API_KEYS=true를 명시적으로 설정하세요.",
-                    )
-
-        if not ALLOW_PLAINTEXT_API_KEYS:
-            raise HTTPException(
-                status_code=500,
-                detail="keyring 패키지를 사용할 수 없어 API 키를 안전하게 저장할 수 없습니다.",
-            )
+    _user_key_runtime = build_user_key_runtime(
+        load_users=load_users,
+        save_users=save_users,
+        ensure_user_identity=ensure_user_identity,
+        keyring=keyring,
+        allow_plaintext_api_keys=ALLOW_PLAINTEXT_API_KEYS,
+        logging=logging,
+        http_exception=HTTPException,
+    )
+    get_history_user = _user_key_runtime["get_history_user"]
+    get_user_api_key = _user_key_runtime["get_user_api_key"]
+    set_user_api_key = _user_key_runtime["set_user_api_key"]
 
-        users = load_users()
-        user = users.get(email)
-        if not user:
-            user = {
-                "password_hash": "",
-                "salt": "",
-                "name": email,
-                "nickname": email,
-                "role": "user",
-                "disabled": False,
-            }
-        ensure_user_identity(email, user)
-        api_keys = user.get("api_keys") or {}
-        api_keys[provider] = key
-        user["api_keys"] = api_keys
-        users[email] = user
-        save_users(users)
+    # Chat service owns persistence and trace behavior after its user-key
+    # dependencies are available.
+    CHAT_SERVICE = ChatService(
+        store=WORKSPACE_OS,
+        get_history=get_history,
+        save_to_history=save_to_history,
+        get_history_user=get_history_user,
+    )
 
     # ── Sensitivity analysis — delegated to latticeai.core.audit ──────────────────
     def classify_sensitive_message(item: Dict, index: int) -> Dict:
@@ -977,8 +681,6 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
         local_server_processes=LOCAL_SERVER_PROCESSES,
         logger=logging,
     )
-    autoload_default_model = _lifespan_runtime["autoload_default_model"]
-    unload_idle_models_loop = _lifespan_runtime["unload_idle_models_loop"]
     _spawn = _lifespan_runtime["_spawn"]
     lifespan = _lifespan_runtime["lifespan"]
 
@@ -993,14 +695,11 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
         static_dir=STATIC_DIR,
     )
     app = _web_runtime["app"]
-    CORS_ALLOWED_ORIGINS = _web_runtime["CORS_ALLOWED_ORIGINS"]
     ensure_agent_root()
 
     OPEN_REGISTRATION = CONFIG.open_registration
-    INVITE_CODE = CONFIG.invite_code
-    INVITE_GATE_ENABLED = CONFIG.invite_gate_enabled
-    configure_model_runtime_from_context(
-        configure_model_runtime=configure_model_runtime,
+    _model_runtime_service = configure_model_runtime_from_context(
+        build_model_runtime=build_model_runtime,
         router=router,
         APP_MODE=APP_MODE,
         DEFAULT_HOST=DEFAULT_HOST,
@@ -1030,6 +729,8 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
         static_dir=STATIC_DIR,
         invite_gate_enabled=INVITE_GATE_ENABLED,
         invite_code=INVITE_CODE,
+        invite_cookie_secret=INVITE_COOKIE_SECRET,
+        secure_cookies=SECURE_COOKIES,
         app_mode=APP_MODE,
         model_router=router,
         require_user=require_user,
@@ -1037,6 +738,7 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
     STATIC_ROUTES = _static_routes_bundle["STATIC_ROUTES"]
     ui_file_response = _static_routes_bundle["ui_file_response"]
     local_sysinfo = _static_routes_bundle["local_sysinfo"]
+    invite_authorized = _static_routes_bundle["invite_authorized"]
 
     # ── Auth & Admin routers (latticeai.api) ─────────────────────────────────────
     _foundation_router_bundle = build_auth_admin_security_router_bundle(
@@ -1059,6 +761,8 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
         open_registration=OPEN_REGISTRATION,
         session_ttl=_SESSION_TTL,
         require_auth=REQUIRE_AUTH,
+        secure_cookies=SECURE_COOKIES,
+        invite_authorized=invite_authorized,
         ensure_identity=ensure_user_identity,
         create_admin_router=create_admin_router,
         require_admin=require_admin,
@@ -1159,6 +863,7 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
         include_image_missing_replies: bool = True,
         user_email: Optional[str] = None,
         conversation_id: Optional[str] = None,
+        workspace_id: Optional[str] = None,
     ) -> str:
         return build_recent_chat_context(
             get_history=get_history,
@@ -1166,6 +871,7 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
             include_image_missing_replies=include_image_missing_replies,
             user_email=user_email,
             conversation_id=conversation_id,
+            workspace_id=workspace_id,
         )
 
     CHAT_AGENT_RUNTIME = build_chat_agent_runtime_from_context(
@@ -1182,7 +888,7 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
 
     # ── Typed dependency context (latticeai.services.app_context) ────────────────
     # One context object replaces the historical 25-30-kwarg router wiring.
-    context = build_app_context(
+    context = AppContext(
         config=CONFIG,
         data_dir=DATA_DIR,
         static_dir=STATIC_DIR,
@@ -1264,6 +970,7 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
         agent_registry=AGENT_REGISTRY,
         data_dir=DATA_DIR,
         append_audit_event=append_audit_event,
+        memory_service=MEMORY_SERVICE,
         tz_name=getattr(CONFIG, "timezone", None),
     )
     _llm_generate_sync = _platform_automation_runtime["_llm_generate_sync"]
@@ -1318,28 +1025,30 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
     # ── Health / status / engine-summary router (latticeai.api.health, v1.2.0) ───
     # /health, /mode, /runtime_features, /engines(GET) now live in the health router.
     # Heavier engine mutation endpoints remain below in server_app.
-    MODEL_SERVICE = register_model_runtime_routers(
+    _model_runtime = register_model_runtime_routers(
         app=app,
         create_health_router=create_health_router,
         create_models_router=create_models_router,
         register_health_and_model_routers=register_health_and_model_routers,
         model_router=router,
-        runtime_features=runtime_features,
+        runtime_service=_model_runtime_service,
+        runtime_features=_model_runtime_service.runtime_features,
         is_public_mode=IS_PUBLIC_MODE,
-        engine_status=engine_status,
+        engine_status=_model_runtime_service.engine_status,
         get_current_user=get_current_user,
         require_auth=REQUIRE_AUTH,
         app_version=APP_VERSION,
         app_mode=APP_MODE,
         require_user=require_user,
+        require_admin=require_admin,
         load_users=load_users,
         get_user_role=get_user_role,
-        install_engine=install_engine,
-        verify_cloud_models=verify_cloud_models,
+        install_engine=_model_runtime_service.install_engine,
+        verify_cloud_models=_model_runtime_service.verify_cloud_models,
         normalize_local_model_request=normalize_local_model_request,
         download_hf_model=download_hf_model,
-        prepare_and_load_model=prepare_and_load_model,
-        prepare_and_load_model_stream=prepare_and_load_model_stream,
+        prepare_and_load_model=_model_runtime_service.prepare_and_load_model,
+        prepare_and_load_model_stream=_model_runtime_service.prepare_and_load_model_stream,
         sse_event=sse_event,
         ensure_ollama_server=ensure_ollama_server,
         local_binary=local_binary,
@@ -1366,7 +1075,8 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
 
     def _allowed_workspaces_for(user):
         # No-auth local mode is single-user: no scoping. With auth, scope
-        # reads to the caller's memberships (legacy-global rows stay visible).
+        # reads to the caller's memberships (legacy-global rows require an
+        # explicit maintenance-only compatibility opt-in).
         if not REQUIRE_AUTH or not user:
             return None
         return PLATFORM.allowed_scopes(user)
@@ -1395,6 +1105,7 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
         install_mcp=install_mcp,
         mcp_public_item=mcp_public_item,
         hooks=HOOKS_REGISTRY,
+        workspace_service=WORKSPACE_SERVICE,
         chat_context=context,
         search_service=SEARCH_SERVICE,
         allowed_workspaces_for=_allowed_workspaces_for,
@@ -1418,10 +1129,9 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
     from latticeai.api.review_queue import create_review_queue_router
     run_review_item = build_review_run_now_runner(PLATFORM, HTTPException)
 
-    BRAIN_NETWORK = register_tail_runtime_routers(
-        app=app,
+    register_review_and_brain_tail_routers(
+        app,
         create_review_queue_router=create_review_queue_router,
-        register_review_and_brain_tail_routers=register_review_and_brain_tail_routers,
         review_queue=REVIEW_QUEUE,
         require_user=require_user,
         gate_read=PLATFORM.gate_read,
@@ -1430,6 +1140,7 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
         append_audit_event=append_audit_event,
         create_browser_router=create_browser_router,
         ingestion_pipeline=INGESTION_PIPELINE,
+        workspace_service=WORKSPACE_SERVICE,
         create_portability_router=create_portability_router,
         kg_portability=KG_PORTABILITY,
         require_admin=require_admin,
@@ -1450,9 +1161,78 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
         uvicorn.run(app, host=DEFAULT_HOST, port=DEFAULT_PORT, log_level="info")
 
     # ── Constructed-namespace export (consumed by AppRuntime) ────────────────
-    # Every local — singletons, helper functions, request models — becomes an
-    # attribute of the runtime so the legacy ``server_app`` surface survives.
-    return dict(locals())
+    # The five stages are typed and the compatibility surface is enumerated;
+    # assembly locals never escape the composition root.
+    router_bundle = build_router_bundle(app, context)
+    runtime_bundle = RuntimeBundle(
+        app=app,
+        CONFIG=CONFIG,
+        KNOWLEDGE_GRAPH=KNOWLEDGE_GRAPH,
+        INGESTION_PIPELINE=INGESTION_PIPELINE,
+        AGENT_RUNTIME=AGENT_RUNTIME,
+        HOOKS_REGISTRY=HOOKS_REGISTRY,
+        REVIEW_QUEUE=REVIEW_QUEUE,
+        AGENT_REGISTRY=AGENT_REGISTRY,
+        model_router=router,
+        build_runtime=build_runtime,
+        get_shared_runtime=get_shared_runtime,
+        create_app=create_app,
+        config_runtime=_config_runtime,
+        security_runtime=_security_runtime,
+        brain_runtime=_brain_runtime,
+        model_runtime=_model_runtime,
+        router_bundle=router_bundle,
+    )
+    return build_runtime_namespace(
+        runtime_bundle=runtime_bundle,
+        legacy_exports={
+            "ENGINE_MODEL_CATALOG": ENGINE_MODEL_CATALOG,
+            "TOOL_GOVERNANCE": TOOL_GOVERNANCE,
+            "enforce_rate_limit": enforce_rate_limit,
+            "filter_lower_family_versions": filter_lower_family_versions,
+            "hash_password": hash_password,
+            "normalize_local_model_request": normalize_local_model_request,
+            "verify_password": verify_password,
+            "_LOCAL_WRITE_BLOCKED_PREFIXES": _LOCAL_WRITE_BLOCKED_PREFIXES,
+            "_RATE_LIMIT_ENABLED": _RATE_LIMIT_ENABLED,
+            "_SESSION_TTL": _SESSION_TTL,
+            "_TOOL_CATALOG_BRIEF": _TOOL_CATALOG_BRIEF,
+            "_TOOL_GOVERNANCE_DEFAULT": _TOOL_GOVERNANCE_DEFAULT,
+            "_agent_risk": _agent_risk,
+            "_allowed_workspaces_for": _allowed_workspaces_for,
+            "_build_admin_audit_report": _build_admin_audit_report,
+            "_build_sensitivity_report": _build_sensitivity_report,
+            "_bytes_match_extension": _bytes_match_extension,
+            "_check_ip_rate_limit": _check_ip_rate_limit,
+            "_check_rate_limit": _check_rate_limit,
+            "_check_tool_role": _check_tool_role,
+            "_classify_sensitive_message": _classify_sensitive_message,
+            "_client_ip": _client_ip,
+            "_create_security_router": _create_security_router,
+            "_embedding_info": _embedding_info,
+            "_fetch_skills_marketplace": _fetch_skills_marketplace,
+            "_get_audit_log": _get_audit_log,
+            "_get_sso_discovery": _get_sso_discovery,
+            "_graph_stats_safe": _graph_stats_safe,
+            "_host_is_loopback": _host_is_loopback,
+            "_list_compat_profiles": _list_compat_profiles,
+            "_llm_generate_sync": _llm_generate_sync,
+            "_product_hardening_status": _product_hardening_status,
+            "_recent_chat_context": _recent_chat_context,
+            "_redact_secret_text": _redact_secret_text,
+            "_require_graph": _require_graph,
+            "_scoped_hybrid_search": _scoped_hybrid_search,
+            "_security_audit_events_safe": _security_audit_events_safe,
+            "_security_list_uploaded_files": _security_list_uploaded_files,
+            "_spawn": _spawn,
+            "_tool_response": _tool_response,
+            "_user_id_for_email": _user_id_for_email,
+            "_workspace_graph": _workspace_graph,
+            "_workspace_models_payload": _workspace_models_payload,
+            "_workspace_scope_from_request": _workspace_scope_from_request,
+            "_workspace_settings_payload": _workspace_settings_payload,
+        },
+    )
 
 
 @dataclass(frozen=True)