ltcai 8.7.0 → 8.9.0

package/docs/COMMUNITY_AND_PLUGINS.md

@@ -1,10 +1,11 @@
 # Community And Plugins
 
-Current release: **8.7.0 — Runtime State Hygiene & Release Evidence Refresh**.
+Current release: **8.9.0 — Scoped Memory & Tool Policy Hardening**.
 
 LatticeAI defines the path from a strong local-first framework (8.4.0
 action-aware baseline, 8.5.0 registry+DI hardening, 8.6.0 capture/navigation
-reliability, and 8.7.0 runtime-state hygiene) to a product ecosystem. The
+reliability, 8.7.0 runtime-state hygiene, 8.8.0 Brain Core extraction
+readiness, and 8.9.0 scoped Tool API hardening) to a product ecosystem. The
 immediate goal is small and practical: make it clear how
 contributors can extend the Brain without weakening local-first trust,
 workspace scoping, or release quality.
@@ -36,7 +37,7 @@ Plugins should add one bounded capability at a time:
 - Compatibility requirements belong in `lattice_version`, and examples should
   use current host-compatible values.
 
-## 8.4.0 Ecosystem Tasks
+## Current Ecosystem Tasks
 
 - Keep the hello-world plugin valid and boring.
 - Expand examples only when they exercise real extension seams.

package/docs/DEVELOPMENT.md

@@ -1,10 +1,10 @@
 # Lattice AI Development
 
-Current release: **8.7.0 — Runtime State Hygiene & Release Evidence Refresh**.
+Current release: **8.9.0 — Scoped Memory & Tool Policy Hardening**.
 
 This document is for contributors working on the local-first Digital Brain
 codebase. Product positioning and quick start stay in `README.md`; release
-history is intentionally limited to 7.0.0-8.7.0 in `docs/CHANGELOG.md` and
+history is intentionally limited to 7.0.0-8.9.0 in `docs/CHANGELOG.md` and
 `RELEASE.md`.
 
 ## Product Contract
@@ -16,8 +16,8 @@ Engineering work should preserve these boundaries:
 
 - the Brain is the durable asset;
 - models are replaceable voices;
-- SQLite is the default local store;
-- PostgreSQL, Docker, cloud models, downloads, update checks, Telegram, and
+- SQLite is the live local Brain store;
+- PostgreSQL scale/migration tooling, Docker, cloud models, downloads, update checks, Telegram, and
   Brain Network are opt-in;
 - import-only paths must not initialize MLX/GPU, write files, or make network
   calls;
@@ -114,10 +114,10 @@ For user-facing, API, runtime, release, or packaging changes, check:
 Release/publish examples must use exact target-version filenames. Do not
 document wildcard artifact upload commands.
 
-For 8.7.0 release work, exact artifacts are:
+For 8.9.0 release work, exact artifacts are:
 
-- `dist/ltcai-8.7.0-py3-none-any.whl`
-- `dist/ltcai-8.7.0.tar.gz`
-- `ltcai-8.7.0.tgz`
-- `dist/ltcai-8.7.0.vsix`
-- `src-tauri/target/release/bundle/dmg/Lattice AI_8.7.0_aarch64.dmg`
+- `dist/ltcai-8.9.0-py3-none-any.whl`
+- `dist/ltcai-8.9.0.tar.gz`
+- `ltcai-8.9.0.tgz`
+- `dist/ltcai-8.9.0.vsix`
+- `src-tauri/target/release/bundle/dmg/Lattice AI_8.9.0_aarch64.dmg`

package/docs/LEGACY_COMPATIBILITY.md

@@ -1,21 +1,40 @@
 # Legacy Compatibility Map
 
-Current release: **8.7.0 — Runtime State Hygiene & Release Evidence Refresh**.
+Current target: **8.9.0 — Scoped Memory & Tool Policy Hardening**.
 
 Lattice AI is moving toward a smaller, modular architecture centered on
 `lattice_brain`, `latticeai.services`, `latticeai.api`, and `latticeai.runtime`.
 Some root-level modules remain packaged for compatibility with older imports,
 CLI entrypoints, or extension workflows. Their presence does not define the
-current 8.7.0 architecture.
+current architecture.
 
-8.7.0 also tracks the inner compatibility layers that sit below the root
-modules. The managed inventory lives in `latticeai.core.legacy_compatibility`
-and groups shims by layer:
+The managed inventory lives in `latticeai.core.legacy_compatibility` and
+groups shims by layer:
 
-- `root`: historical repo-root imports such as `knowledge_graph.py`.
-- `brain-flat`: pre-graph-package imports such as `lattice_brain.store`.
-- `deprecated-namespace`: older `latticeai.brain.*` package imports.
-- `service-alias`: service paths that now alias Brain runtime modules.
+- `root`: historical repo-root imports such as `knowledge_graph.py` — **kept**
+  (external entrypoints: `uvicorn server:app`, installed CLI, old scripts).
+- `brain-flat`: pre-graph-package imports such as `lattice_brain.store` —
+  **removed in 8.8.0** (internal-only).
+- `deprecated-namespace`: older `latticeai.brain.*` package imports —
+  **removed in 8.8.0** (internal-only).
+- `service-alias`: `latticeai.services.agent_runtime` —
+  **removed in 8.8.0** (internal-only).
+
+Removed layers stay listed in `legacy_compatibility.REMOVED_SHIMS` and in the
+`legacy_shim_report()` payload (`removed`, `lingering`), so tooling can tell
+"removed on purpose" apart from "missing by accident".
+
+## Brain Core extraction readiness
+
+Removing the internal layers gives `lattice_brain` exactly one import surface
+(its physical module paths). Two structural guards keep it extractable as a
+standalone package:
+
+- `tests/unit/test_brain_core_isolation.py` — AST guard that fails if any
+  `lattice_brain` module imports `latticeai` (the product imports the Brain,
+  never the reverse).
+- `tests/unit/test_legacy_root_shims.py::test_internal_shim_layers_are_gone`
+  — fails if a removed shim path becomes importable again.
 
 ## Current Policy
 
@@ -47,13 +66,13 @@ and groups shims by layer:
 | `setup_wizard.py` | setup and model recommendation services | Compatibility for first-run recommendation calls |
 | `server.py` | lazy proxy to `latticeai.server_app` / `latticeai.app_factory` | Preserves historical `server.app` imports without import-time construction |
 
-## Inner Shim Layers
+## Inner Shim Layers (removed in 8.8.0)
 
-| Legacy layer | Example module | Current home / direction | Why it remains |
+| Legacy layer | Example module | Replacement import | Status |
 | --- | --- | --- | --- |
-| `brain-flat` | `lattice_brain.store`, `lattice_brain.ingest`, `lattice_brain.retrieval` | `lattice_brain.graph.*` | Preserves imports from before graph modules were split into a package |
-| `deprecated-namespace` | `latticeai.brain.store`, `latticeai.brain.ingest` | `lattice_brain.graph.*` | Preserves the old application-package Brain namespace |
-| `service-alias` | `latticeai.services.agent_runtime` | `lattice_brain.runtime.agent_runtime` | Preserves service-layer imports while runtime ownership sits in Brain Core |
+| `brain-flat` | `lattice_brain.store`, `lattice_brain.ingest`, `lattice_brain.retrieval` | `lattice_brain.graph.*` | Removed — internal-only, no supported entrypoint depended on it |
+| `deprecated-namespace` | `latticeai.brain.*` | `lattice_brain.*` | Removed — namespace also dropped from `pyproject.toml` packages |
+| `service-alias` | `latticeai.services.agent_runtime` | `lattice_brain.runtime.agent_runtime` | Removed — runtime ownership sits in Brain Core |
 
 ## Packaging Notes
 

package/docs/ONBOARDING.md

@@ -1,6 +1,6 @@
 # Lattice AI Onboarding
 
-Current release: **8.7.0 — Runtime State Hygiene & Release Evidence Refresh**.
+Current release: **8.9.0 — Scoped Memory & Tool Policy Hardening**.
 
 The first-run goal is a five-minute path from "I opened the app" to "my Brain
 has a source, a question, and proof." This page is the product contract behind
@@ -32,7 +32,7 @@ read the docs first.
 
 ## Release Gate
 
-8.7.0 treats onboarding as a release gate, not marketing copy. The current
+8.9.0 treats onboarding as a release gate, not marketing copy. The current
 machine-checkable product readiness report requires this five-minute contract,
 the Brain Home surface, setup helpers, graph ingestion tests, and exact release
 artifact documentation before the release can be called complete.

package/docs/PRODUCT_DIRECTION_REVIEW.md

@@ -23,8 +23,9 @@ Already aligned:
 - The post-setup home is the living Brain plus conversation.
 - The graph appears only after progressive depth: Brain -> Memories ->
   Knowledge -> Relationships -> Graph.
-- Brain Core, SQLite default storage, optional PostgreSQL/pgvector scale mode,
-  backup/restore, and encrypted `.latticebrain` archives support user ownership.
+- Brain Core, SQLite live local storage, optional PostgreSQL/pgvector
+  scale/migration tooling, backup/restore, and encrypted `.latticebrain`
+  archives support user ownership.
 - Models are treated as swappable runtime workers rather than the durable asset.
 
 Gaps corrected in this review:

package/docs/TRUST_MODEL.md

@@ -1,6 +1,6 @@
 # Lattice AI Trust Model
 
-Current release: **8.7.0 — Runtime State Hygiene & Release Evidence Refresh**.
+Current release: **8.9.0 — Scoped Memory & Tool Policy Hardening**.
 
 Lattice AI is local-first, explicit about external communication, and honest
 when a capability is unavailable.
@@ -34,6 +34,10 @@ External communication requires configuration plus a user/admin action:
 
 Token presence alone must not start external communication.
 
+Authenticated history, Knowledge Graph reads, and Tool API calls must also stay
+inside the caller's user/workspace scope. Direct HTTP/MCP tool routes run
+ToolRegistry policy before hooks or handlers execute.
+
 ## Consent And Honesty Gates
 
 Lattice AI should fail closed or show an unavailable state for:

package/docs/WHY_LATTICE.md

@@ -1,6 +1,6 @@
 # Why Lattice AI Exists
 
-Current release: **8.7.0 — Runtime State Hygiene & Release Evidence Refresh**.
+Current release: **8.9.0 — Scoped Memory & Tool Policy Hardening**.
 
 **Lattice AI is a local-first Digital Brain that keeps your knowledge durable
 across any AI model.**
@@ -32,8 +32,9 @@ The graph matters, but it is not the product identity. The product identity is a
 local-first Digital Brain: a place where the user can talk, add sources, watch
 memory grow, and inspect the Knowledge Graph when they need proof.
 
-In 8.7.0 the first screen is intentionally not a dashboard. The living Brain,
-conversation composer, evidence-backed Brain Brief, and five-minute onboarding
+In 8.9.0 the first screen is intentionally not a dashboard. The living Brain,
+conversation composer, evidence-backed Brain Brief, scoped memory isolation,
+and five-minute onboarding
 path appear together so the user immediately knows what matters, what to add,
 and why the answer is grounded in local memory.
 

package/docs/architecture.md

@@ -1,5 +1,9 @@
 # Lattice AI Architecture
 
+> Historical subsystem note. The canonical current architecture document is
+> [`ARCHITECTURE.md`](../ARCHITECTURE.md). This file preserves the v3.6.0
+> Knowledge Graph First architecture detail for background.
+
 > v3.6.0 — **Knowledge Graph First.** Every data source converges into the graph
 > through one unified ingestion pipeline (`latticeai/services/ingestion.py`), with
 > formalized entities/relationships (`docs/kg-schema.md`), browser/web inputs,

package/docs/kg-schema.md

@@ -1,6 +1,6 @@
 # Knowledge Graph Schema
 
-Current release: **8.7.0 — Runtime State Hygiene & Release Evidence Refresh**.
+Current release: **8.9.0 — Scoped Memory & Tool Policy Hardening**.
 
 명세 출처: `lattice_ai_full_spec.pptx` 슬라이드 20·21·22
 구현: `kg_schema.py`

package/kg_schema.py

@@ -1,3 +1,3 @@
 """Compatibility shim for the v4 Knowledge Graph schema."""
 
-from lattice_brain.schema import *  # noqa: F403,F401
+from lattice_brain.graph.schema import *  # noqa: F403,F401

package/knowledge_graph.py

@@ -4,7 +4,7 @@ The implementation now lives under :mod:`lattice_brain`. Root imports are
 kept for older integrations and tests.
 """
 
-from lattice_brain._kg_common import (  # noqa: F401
+from lattice_brain.graph._kg_common import (  # noqa: F401
     EDGE_VERB,
     GRAPH_SCHEMA_VERSION,
     LOCAL_CODE_EXTENSIONS,
@@ -24,7 +24,7 @@ from lattice_brain._kg_common import (  # noqa: F401
     _slug,
     set_llm_router,
 )
-from lattice_brain.store import KnowledgeGraphStore
+from lattice_brain.graph.store import KnowledgeGraphStore
 
 __all__ = [
     "KnowledgeGraphStore",

package/lattice_brain/__init__.py

@@ -26,7 +26,7 @@ from .storage import (
     storage_from_env,
 )
 
-__version__ = "8.7.0"
+__version__ = "8.9.0"
 
 __all__ = [
     "AgentRuntime",

package/lattice_brain/conversations.py

@@ -60,27 +60,76 @@ class ConversationStore:
                   user_nickname TEXT,
                   source TEXT,
                   timestamp TEXT NOT NULL,
-                  metadata_json TEXT NOT NULL DEFAULT '{}'
+                  metadata_json TEXT NOT NULL DEFAULT '{}',
+                  workspace_id TEXT,
+                  organization_id TEXT
                 );
                 CREATE INDEX IF NOT EXISTS idx_conv_messages_conv
                   ON conversation_messages(conversation_id);
                 CREATE INDEX IF NOT EXISTS idx_conv_messages_time
                   ON conversation_messages(timestamp);
+                CREATE INDEX IF NOT EXISTS idx_conv_messages_user
+                  ON conversation_messages(user_email);
                 """
             )
+            columns = {row["name"] for row in conn.execute("PRAGMA table_info(conversation_messages)").fetchall()}
+            if "workspace_id" not in columns:
+                conn.execute("ALTER TABLE conversation_messages ADD COLUMN workspace_id TEXT")
+            if "organization_id" not in columns:
+                conn.execute("ALTER TABLE conversation_messages ADD COLUMN organization_id TEXT")
+            conn.execute(
+                """
+                CREATE INDEX IF NOT EXISTS idx_conv_messages_workspace
+                  ON conversation_messages(workspace_id)
+                """
+            )
+            rows = conn.execute(
+                """
+                SELECT id, metadata_json FROM conversation_messages
+                WHERE workspace_id IS NULL OR organization_id IS NULL
+                """
+            ).fetchall()
+            for row in rows:
+                try:
+                    meta = json.loads(row["metadata_json"] or "{}")
+                except Exception:
+                    meta = {}
+                workspace_id = meta.get("workspace_id")
+                organization_id = meta.get("organization_id")
+                if workspace_id or organization_id:
+                    conn.execute(
+                        """
+                        UPDATE conversation_messages
+                        SET workspace_id=COALESCE(workspace_id, ?),
+                            organization_id=COALESCE(organization_id, ?)
+                        WHERE id=?
+                        """,
+                        (workspace_id, organization_id, row["id"]),
+                    )
 
     # ── writes ────────────────────────────────────────────────────────────
     def append(self, item: Dict[str, Any]) -> Dict[str, Any]:
         """Persist one chat item (the legacy chat_history.json entry shape)."""
-        known = {"role", "content", "timestamp", "user_email", "user_nickname", "source", "conversation_id"}
+        known = {
+            "role",
+            "content",
+            "timestamp",
+            "user_email",
+            "user_nickname",
+            "source",
+            "conversation_id",
+            "workspace_id",
+            "organization_id",
+        }
         extra = {k: v for k, v in item.items() if k not in known}
         with self._lock, self._connect() as conn:
             conn.execute(
                 """
                 INSERT OR IGNORE INTO conversation_messages
                   (message_hash, conversation_id, role, content, user_email,
-                   user_nickname, source, timestamp, metadata_json)
-                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+                   user_nickname, source, timestamp, metadata_json, workspace_id,
+                   organization_id)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
                 """,
                 (
                     _message_hash(item),
@@ -92,6 +141,8 @@ class ConversationStore:
                     item.get("source"),
                     str(item.get("timestamp") or ""),
                     json.dumps(extra, ensure_ascii=False) if extra else "{}",
+                    item.get("workspace_id"),
+                    item.get("organization_id"),
                 ),
             )
         return item
@@ -122,8 +173,9 @@ class ConversationStore:
                     """
                     INSERT OR IGNORE INTO conversation_messages
                       (message_hash, conversation_id, role, content, user_email,
-                       user_nickname, source, timestamp, metadata_json)
-                    VALUES (?, ?, ?, ?, ?, ?, ?, ?, '{}')
+                       user_nickname, source, timestamp, metadata_json, workspace_id,
+                       organization_id)
+                    VALUES (?, ?, ?, ?, ?, ?, ?, ?, '{}', ?, ?)
                     """,
                     (
                         _message_hash(item),
@@ -134,6 +186,8 @@ class ConversationStore:
                         item.get("user_nickname"),
                         item.get("source"),
                         str(item.get("timestamp") or ""),
+                        item.get("workspace_id"),
+                        item.get("organization_id"),
                     ),
                 )
                 imported += cur.rowcount if cur.rowcount > 0 else 0
@@ -149,7 +203,7 @@ class ConversationStore:
             "content": row["content"],
             "timestamp": row["timestamp"],
         }
-        for key in ("user_email", "user_nickname", "source", "conversation_id"):
+        for key in ("user_email", "user_nickname", "source", "conversation_id", "workspace_id", "organization_id"):
             if row[key]:
                 item[key] = row[key]
         try:
@@ -159,13 +213,62 @@ class ConversationStore:
         item.update(extra)
         return item
 
-    def history(self, *, conversation_id: Optional[str] = None, limit: Optional[int] = None) -> List[Dict[str, Any]]:
+    @staticmethod
+    def _scope_sql(
+        *,
+        user_email: Optional[str] = None,
+        allowed_workspaces: Optional[Any] = None,
+        include_legacy_global: bool = True,
+    ) -> tuple[str, List[Any]]:
+        clauses: List[str] = []
+        params: List[Any] = []
+        if user_email:
+            if include_legacy_global:
+                clauses.append("(user_email = ? OR user_email IS NULL OR user_email = '')")
+            else:
+                clauses.append("user_email = ?")
+            params.append(user_email)
+        if allowed_workspaces is not None:
+            allowed = [str(item) for item in allowed_workspaces if item]
+            if allowed:
+                placeholders = ",".join("?" for _ in allowed)
+                if include_legacy_global:
+                    clauses.append(f"(workspace_id IN ({placeholders}) OR workspace_id IS NULL OR workspace_id = '')")
+                else:
+                    clauses.append(f"workspace_id IN ({placeholders})")
+                params.extend(allowed)
+            elif include_legacy_global:
+                clauses.append("(workspace_id IS NULL OR workspace_id = '')")
+            else:
+                clauses.append("1=0")
+        return " AND ".join(clauses), params
+
+    def history(
+        self,
+        *,
+        conversation_id: Optional[str] = None,
+        limit: Optional[int] = None,
+        user_email: Optional[str] = None,
+        allowed_workspaces: Optional[Any] = None,
+        include_legacy_global: bool = True,
+    ) -> List[Dict[str, Any]]:
         """Chronological items; the unbounded successor of get_history()."""
         query = "SELECT * FROM conversation_messages"
         params: List[Any] = []
+        where: List[str] = []
         if conversation_id is not None:
-            query += " WHERE conversation_id IS ?" if conversation_id == "" else " WHERE conversation_id = ?"
+            where.append("conversation_id IS ?" if conversation_id == "" else "conversation_id = ?")
             params.append(None if conversation_id == "" else conversation_id)
+        scope_sql, scope_params = self._scope_sql(
+            user_email=user_email,
+            allowed_workspaces=allowed_workspaces,
+            include_legacy_global=include_legacy_global,
+        )
+        if scope_sql:
+            where.append(scope_sql)
+            params.extend(scope_params)
+        if where:
+            query += " WHERE " + " AND ".join(where)
         query += " ORDER BY id ASC"
         if limit is not None:
             query += " LIMIT ?"
@@ -185,25 +288,51 @@ class ConversationStore:
             return 0
 
     # ── clears (legacy semantics preserved) ───────────────────────────────
-    def clear_all(self, keep_last: int = 0) -> Dict[str, Any]:
+    def clear_all(
+        self,
+        keep_last: int = 0,
+        *,
+        user_email: Optional[str] = None,
+        allowed_workspaces: Optional[Any] = None,
+        include_legacy_global: bool = True,
+    ) -> Dict[str, Any]:
         keep_last = max(0, min(int(keep_last or 0), 20))
         with self._lock, self._connect() as conn:
             total = conn.execute("SELECT COUNT(*) FROM conversation_messages").fetchone()[0]
+            scope_sql, scope_params = self._scope_sql(
+                user_email=user_email,
+                allowed_workspaces=allowed_workspaces,
+                include_legacy_global=include_legacy_global,
+            )
+            scope_where = f" WHERE {scope_sql}" if scope_sql else ""
             if keep_last:
                 conn.execute(
-                    """
-                    DELETE FROM conversation_messages WHERE id NOT IN (
-                      SELECT id FROM conversation_messages ORDER BY id DESC LIMIT ?
+                    f"""
+                    DELETE FROM conversation_messages
+                    WHERE id IN (
+                      SELECT id FROM conversation_messages{scope_where}
+                    )
+                    AND id NOT IN (
+                      SELECT id FROM conversation_messages{scope_where}
+                      ORDER BY id DESC LIMIT ?
                     )
                     """,
-                    (keep_last,),
+                    (*scope_params, *scope_params, keep_last),
                 )
             else:
-                conn.execute("DELETE FROM conversation_messages")
+                conn.execute(f"DELETE FROM conversation_messages{scope_where}", scope_params)
             kept = conn.execute("SELECT COUNT(*) FROM conversation_messages").fetchone()[0]
         return {"status": "cleared", "removed": max(0, total - kept), "kept": kept}
 
-    def clear_conversation(self, conversation_id: str, started_at: Optional[str] = None) -> Dict[str, Any]:
+    def clear_conversation(
+        self,
+        conversation_id: str,
+        started_at: Optional[str] = None,
+        *,
+        user_email: Optional[str] = None,
+        allowed_workspaces: Optional[Any] = None,
+        include_legacy_global: bool = True,
+    ) -> Dict[str, Any]:
         """Remove one conversation.
 
         ``legacy-previous-history`` targets unattributed messages; when
@@ -212,17 +341,23 @@ class ConversationStore:
         """
         with self._lock, self._connect() as conn:
             total = conn.execute("SELECT COUNT(*) FROM conversation_messages").fetchone()[0]
+            scope_sql, scope_params = self._scope_sql(
+                user_email=user_email,
+                allowed_workspaces=allowed_workspaces,
+                include_legacy_global=include_legacy_global,
+            )
+            scoped = f" AND {scope_sql}" if scope_sql else ""
             if conversation_id == "legacy-previous-history":
-                conn.execute("DELETE FROM conversation_messages WHERE conversation_id IS NULL")
+                conn.execute(f"DELETE FROM conversation_messages WHERE conversation_id IS NULL{scoped}", scope_params)
             else:
                 conn.execute(
-                    "DELETE FROM conversation_messages WHERE conversation_id = ?",
-                    (conversation_id,),
+                    f"DELETE FROM conversation_messages WHERE conversation_id = ?{scoped}",
+                    (conversation_id, *scope_params),
                 )
                 if started_at:
                     conn.execute(
-                        "DELETE FROM conversation_messages WHERE conversation_id IS NULL AND timestamp >= ?",
-                        (str(started_at),),
+                        f"DELETE FROM conversation_messages WHERE conversation_id IS NULL AND timestamp >= ?{scoped}",
+                        (str(started_at), *scope_params),
                     )
             kept = conn.execute("SELECT COUNT(*) FROM conversation_messages").fetchone()[0]
         return {

package/lattice_brain/core.py

@@ -40,7 +40,7 @@ class BrainCore:
             )
 
         from .conversations import ConversationStore
-        from .store import KnowledgeGraphStore
+        from .graph.store import KnowledgeGraphStore
 
         self.knowledge = KnowledgeGraphStore(
             self.db_path,

package/lattice_brain/graph/_kg_common.py

@@ -34,6 +34,8 @@ except Exception:  # pragma: no cover - v2 schema is optional at import time
     _exec_script = None  # type: ignore[assignment]
 
 from ..embeddings import LocalEmbeddingModel
+from .json_utils import _json, _safe_loads
+from .runtime import get_llm_router, set_llm_router
 
 # Default read source for the graph queries: v2 reconstruction views.
 # Override with LATTICEAI_KG_READ_V2=0 to fall back to the legacy tables.
@@ -48,14 +50,6 @@ _KG_DB_FORMAT_VERSION = 4
 _KG_DB_FORMAT_KEY = "db_format_version"
 _V2_WRITE_MASTER_KEY = "v2_write_mastered_at"
 
-_llm_router_ref = None
-
-
-def set_llm_router(router_instance):
-    global _llm_router_ref
-    _llm_router_ref = router_instance
-
-
 GRAPH_SCHEMA_VERSION = 1
 
 LOCAL_TEXT_EXTENSIONS = {".txt", ".md"}
@@ -286,24 +280,6 @@ def _recency_score(
     return math.exp(-decay * age_days)
 
 
-def _json(data: Optional[Dict[str, Any]]) -> str:
-    return json.dumps(data or {}, ensure_ascii=False, sort_keys=True)
-
-
-def _safe_loads(raw: Optional[str]) -> Dict[str, Any]:
-    """Tolerantly parse a metadata_json column — returns {} on corrupt rows."""
-    if not raw:
-        return {}
-    try:
-        value = json.loads(raw)
-        return value if isinstance(value, dict) else {}
-    except (json.JSONDecodeError, TypeError) as e:
-        logging.warning(
-            "knowledge_graph: corrupt metadata_json (%s) — using empty dict", e
-        )
-        return {}
-
-
 def _slug(text: str, max_len: int = 96) -> str:
     value = re.sub(r"\s+", " ", str(text or "")).strip().lower()
     value = re.sub(r"[^0-9a-zA-Z가-힣._:@/-]+", "-", value).strip("-")
@@ -586,9 +562,10 @@ ENABLE_LLM_EXTRACTION = os.getenv("LATTICEAI_LLM_EXTRACTION", "true").lower() in
 
 
 def _llm_extract_concepts(text: str, limit: int = 12) -> Optional[List[str]]:
-    if not ENABLE_LLM_EXTRACTION or not _llm_router_ref:
+    router = get_llm_router()
+    if not ENABLE_LLM_EXTRACTION or not router:
         return None
-    if not _llm_router_ref.current_model_id:
+    if not router.current_model_id:
         return None
     prompt = _LLM_EXTRACT_CONCEPT_PROMPT.format(text=text[:3000], limit=limit)
     try:
@@ -599,12 +576,12 @@ def _llm_extract_concepts(text: str, limit: int = 12) -> Optional[List[str]]:
             with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
                 future = pool.submit(
                     asyncio.run,
-                    _llm_router_ref.generate(prompt, max_tokens=1024, temperature=0.1),
+                    router.generate(prompt, max_tokens=1024, temperature=0.1),
                 )
                 raw = future.result(timeout=30)
         else:
             raw = asyncio.run(
-                _llm_router_ref.generate(prompt, max_tokens=1024, temperature=0.1)
+                router.generate(prompt, max_tokens=1024, temperature=0.1)
             )
         raw = raw.strip()
         if raw.startswith("```"):
@@ -627,9 +604,10 @@ def _llm_extract_concepts(text: str, limit: int = 12) -> Optional[List[str]]:
 def _llm_extract_triples(
     text: str, concepts: List[str], limit: int = 20
 ) -> Optional[List[Dict[str, str]]]:
-    if not ENABLE_LLM_EXTRACTION or not _llm_router_ref:
+    router = get_llm_router()
+    if not ENABLE_LLM_EXTRACTION or not router:
         return None
-    if not _llm_router_ref.current_model_id:
+    if not router.current_model_id:
         return None
     prompt = _LLM_EXTRACT_TRIPLE_PROMPT.format(
         text=text[:3000],
@@ -644,12 +622,12 @@ def _llm_extract_triples(
             with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
                 future = pool.submit(
                     asyncio.run,
-                    _llm_router_ref.generate(prompt, max_tokens=2048, temperature=0.1),
+                    router.generate(prompt, max_tokens=2048, temperature=0.1),
                 )
                 raw = future.result(timeout=30)
         else:
             raw = asyncio.run(
-                _llm_router_ref.generate(prompt, max_tokens=2048, temperature=0.1)
+                router.generate(prompt, max_tokens=2048, temperature=0.1)
             )
         raw = raw.strip()
         if raw.startswith("```"):