ltcai 10.3.0 → 10.4.0

package/lattice_brain/graph/_kg_common.py

@@ -29,9 +29,9 @@ from typing import Any, Dict, Iterable, Iterator, List, Optional, Tuple
 try:
     from .schema import EdgeType, KGStoreV2, NodeType, _exec_script
 except Exception:  # pragma: no cover - v2 schema is optional at import time
-    KGStoreV2 = None  # type: ignore[assignment]
-    NodeType = None  # type: ignore[assignment]
-    EdgeType = None  # type: ignore[assignment]
+    KGStoreV2 = None  # type: ignore[assignment,misc]
+    NodeType = None  # type: ignore[assignment,misc]
+    EdgeType = None  # type: ignore[assignment,misc]
     _exec_script = None  # type: ignore[assignment]
 
 from ..embeddings import LocalEmbeddingModel
@@ -69,9 +69,33 @@ from ._kg_constants import (  # noqa: E402
     WINDOWS_EXCLUDED_NAMES,
 )
 
-# Pure fs/path/hash/classification helpers → ._kg_fsutil (re-exported so the
-# computed __all__ below still forwards them to the graph mixins).
-from ._kg_fsutil import *  # noqa: E402,F401,F403
+# Pure fs/path/hash/classification helpers → ._kg_fsutil, re-exported so the
+# static __all__ below forwards them to the graph mixins. Listed explicitly
+# rather than star-imported: a star import here made every name in this
+# module unverifiable to both ruff and mypy.
+from ._kg_fsutil import (  # noqa: E402,F401
+    _current_os_type,
+    _drive_id_for_path,
+    _excluded_directory_reason,
+    _file_category,
+    _is_hidden_path,
+    _is_relative_to,
+    _node_type_for_category,
+    _now,
+    _parse_iso,
+    _parser_type_for_category,
+    _path_fingerprint,
+    _path_parts_lower,
+    _recency_score,
+    _root_warning,
+    _safe_iso_from_stat_mtime,
+    _sample_file,
+    _sensitive_file_reason,
+    _sha256_bytes,
+    _sha256_text,
+    _size_limit_for_category,
+    _slug,
+)
 
 
 def _clean_text(text: str) -> str:
@@ -613,9 +637,11 @@ def _llm_extract_concepts(text: str, limit: int = 12) -> Optional[List[str]]:
     return None
 
 
+# Triples carry a numeric ``weight``/``confidence`` alongside string fields,
+# so the value type is Any rather than str.
 def _llm_extract_triples(
     text: str, concepts: List[str], limit: int = 20
-) -> Optional[List[Dict[str, str]]]:
+) -> Optional[List[Dict[str, Any]]]:
     router = get_llm_router()
     if not ENABLE_LLM_EXTRACTION or not router:
         return None
@@ -647,7 +673,7 @@ def _llm_extract_triples(
             raw = re.sub(r"\s*```$", "", raw)
         parsed = json.loads(raw)
         if isinstance(parsed, list):
-            triples = []
+            triples: List[Dict[str, Any]] = []
             for item in parsed[:limit]:
                 if isinstance(item, dict) and "subject" in item and "object" in item:
                     relation = str(item.get("relation", "관련됨"))
@@ -1173,4 +1199,133 @@ def _topic_candidates(text: str, limit: int = 8) -> List[str]:
     return list(seen.values())[:limit]
 
 
-__all__ = [name for name in globals() if not name.startswith("__")]
+# Static export list. This used to be `[name for name in globals() if not
+# name.startswith("__")]`, which is invisible to a type checker: every
+# `from ._kg_common import *` consumer then had *no* resolvable names, and
+# mypy reported ~750 spurious `name-defined` errors across the graph
+# package. `tests/unit/test_kg_common_exports.py` asserts this list still
+# equals what the computed expression would produce, so it cannot drift.
+__all__ = [
+    "Any",
+    "COMMON_EXCLUDED_DIRS",
+    "COMMON_EXCLUDED_FILE_NAMES",
+    "COMMON_EXCLUDED_FILE_SUFFIXES",
+    "COOCCURRENCE_CONCEPT_LIMIT",
+    "COOCCURRENCE_EDGE_WEIGHT",
+    "Counter",
+    "Dict",
+    "EDGE_VERB",
+    "ENABLE_LLM_EXTRACTION",
+    "EdgeType",
+    "GRAPH_SCHEMA_VERSION",
+    "Iterable",
+    "Iterator",
+    "KGStoreV2",
+    "LINUX_EXCLUDED_PREFIXES",
+    "LOCAL_CODE_EXTENSIONS",
+    "LOCAL_DOCUMENT_EXTENSIONS",
+    "LOCAL_IMAGE_EXTENSIONS",
+    "LOCAL_SIZE_LIMITS",
+    "LOCAL_SLIDE_EXTENSIONS",
+    "LOCAL_SPREADSHEET_EXTENSIONS",
+    "LOCAL_SUPPORTED_EXTENSIONS",
+    "LOCAL_TEXT_EXTENSIONS",
+    "List",
+    "LocalEmbeddingModel",
+    "MACOS_EXCLUDED_PREFIXES",
+    "NodeType",
+    "Optional",
+    "Path",
+    "SENSITIVE_PATH_KEYWORDS",
+    "Tuple",
+    "VERB_EDGE_WEIGHT",
+    "WINDOWS_EXCLUDED_NAMES",
+    "_CHUNK_STRATEGIES",
+    "_CODE_BLANK_RUN_RE",
+    "_CODE_BOUNDARY_LINE_RE",
+    "_CODE_CHUNK_EXTENSIONS",
+    "_CONCEPT_STOP",
+    "_KG_DB_FORMAT_KEY",
+    "_KG_DB_FORMAT_VERSION",
+    "_LLM_EXTRACT_CONCEPT_PROMPT",
+    "_LLM_EXTRACT_TRIPLE_PROMPT",
+    "_MARKDOWN_CHUNK_EXTENSIONS",
+    "_MARKDOWN_HEADING_RE",
+    "_MARKDOWN_MIN_SECTION_CHARS",
+    "_NOT_PERSON_WORDS",
+    "_PROJECTION_VERSION",
+    "_PROSE_CHUNK_EXTENSIONS",
+    "_PROSE_MIN_SPAN_RATIO",
+    "_PROSE_STRONG_BOUNDARY_RE",
+    "_PROSE_WEAK_BOUNDARY_RE",
+    "_READ_FROM_V2_DEFAULT",
+    "_V2_WRITE_MASTER_KEY",
+    "_chunks",
+    "_classify_node_type",
+    "_clean_text",
+    "_code_chunks",
+    "_code_segment_spans",
+    "_current_os_type",
+    "_drive_id_for_path",
+    "_excluded_directory_reason",
+    "_exec_script",
+    "_extract_concepts",
+    "_extract_concepts_rules",
+    "_extract_triples",
+    "_extract_triples_rules",
+    "_file_category",
+    "_infer_edge",
+    "_is_hidden_path",
+    "_is_relative_to",
+    "_json",
+    "_last_boundary",
+    "_llm_extract_concepts",
+    "_llm_extract_triples",
+    "_markdown_chunks",
+    "_markdown_section_spans",
+    "_merge_small_sections",
+    "_node_type_for_category",
+    "_now",
+    "_parse_iso",
+    "_parser_type_for_category",
+    "_path_fingerprint",
+    "_path_parts_lower",
+    "_plain_windows",
+    "_prose_chunks",
+    "_recency_score",
+    "_root_warning",
+    "_safe_iso_from_stat_mtime",
+    "_safe_loads",
+    "_sample_file",
+    "_semantic_items",
+    "_sensitive_file_reason",
+    "_sha256_bytes",
+    "_sha256_text",
+    "_size_limit_for_category",
+    "_slug",
+    "_topic_candidates",
+    "asyncio",
+    "chunk_strategy_for",
+    "citation_locator",
+    "contextmanager",
+    "datetime",
+    "get_llm_router",
+    "hashlib",
+    "infer_edge_relation",
+    "json",
+    "logging",
+    "math",
+    "os",
+    "page_for_offset",
+    "pdf_page_offsets",
+    "platform",
+    "quiet",
+    "re",
+    "set_llm_router",
+    "shutil",
+    "sqlite3",
+    "time",
+    "typed_chunk_meta_fields",
+    "typed_chunks",
+    "zipfile",
+]

package/lattice_brain/graph/_kg_contract.py

@@ -0,0 +1,223 @@
+"""The seam eleven graph mixins share.
+
+``KnowledgeGraphStore`` is assembled from eleven mixins that freely call each
+other's methods — ``ingest`` calls ``_upsert_node`` from ``write_master``,
+``write_master`` calls ``_v2_project_node`` from ``projection``, everything
+calls ``_connect`` from the store itself. That contract existed, but nowhere in
+the code: a reader had to grep eleven files to learn what a mixin may assume,
+and a type checker reported 229 ``attr-defined`` errors because from *its*
+position each mixin is a bare class calling methods it does not have.
+
+This module writes the contract down. It is **typing-only** — the mixins alias
+it to ``object`` at runtime, so the MRO and every method resolution are
+byte-for-byte what they were. What changes is that the shared surface is now 23
+declared names in one file instead of an unwritten convention, and adding a
+cross-mixin call without declaring it here is a type error.
+
+Signatures mirror the real implementations; ``tests/unit/test_kg_contract.py``
+asserts the concrete store still provides every member.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from contextlib import AbstractContextManager
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple
+
+
+class KnowledgeGraphCore:
+    """What any graph mixin may assume about ``self``.
+
+    Never instantiated and never inherited at runtime — see the module
+    docstring. Members are declared, not implemented, on purpose: the concrete
+    implementation lives in whichever mixin owns it.
+    """
+
+    # ── State owned by KnowledgeGraphStore.__init__ ──────────────────────────
+    db_path: Path
+    blob_dir: Path
+    storage_engine: Any
+    _embedding_model: Any
+    _read_from_v2: bool
+    _v2_projection_available: bool
+
+    # ── store.py: connection + read-table resolution ─────────────────────────
+    def _connect(self) -> AbstractContextManager[sqlite3.Connection]:
+        """Transactional connection that is *closed* when the block exits."""
+        raise NotImplementedError
+
+    def _read_tables(self) -> Tuple[str, ...]:
+        """``(nodes_table, edges_table)`` — legacy tables or the v2 views."""
+        raise NotImplementedError
+
+    # ── write_master.py: the single write door ───────────────────────────────
+    def _upsert_node(
+        self,
+        conn: sqlite3.Connection,
+        node_id: str,
+        node_type: str,
+        title: str,
+        summary: str = "",
+        metadata: Optional[Dict[str, Any]] = None,
+        raw: Optional[Dict[str, Any]] = None,
+        owner: Optional[str] = None,
+        workspace_id: Optional[str] = None,
+        visibility: Optional[str] = None,
+    ) -> str:
+        raise NotImplementedError
+
+    def _upsert_edge(
+        self,
+        conn: sqlite3.Connection,
+        from_node: str,
+        to_node: str,
+        edge_type: str,
+        weight: float = 1.0,
+        metadata: Optional[Dict[str, Any]] = None,
+        *,
+        legacy_label: Optional[str] = None,
+    ) -> str:
+        raise NotImplementedError
+
+    def _upsert_chunk(
+        self,
+        conn: sqlite3.Connection,
+        *,
+        chunk_id: str,
+        source_node: str,
+        text: str,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        raise NotImplementedError
+
+    def _upsert_vector_item(
+        self,
+        conn: sqlite3.Connection,
+        *,
+        item_id: str,
+        item_type: str,
+        source_node: str,
+        text: str,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> bool:
+        raise NotImplementedError
+
+    def _vector_text_for_node(
+        self,
+        *,
+        title: str,
+        summary: str = "",
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> str:
+        raise NotImplementedError
+
+    # ── projection.py: legacy ↔ v2 projection + keyword index ────────────────
+    def _v2_project_node(
+        self,
+        conn: sqlite3.Connection,
+        node_id: str,
+        node_type: str,
+        title: str,
+        summary: Optional[str],
+        metadata_json: Optional[str],
+        *,
+        created_at: Optional[str] = None,
+        updated_at: Optional[str] = None,
+        owner: Optional[str] = None,
+        workspace_id: Optional[str] = None,
+        visibility: Optional[str] = None,
+        strict: bool = False,
+    ) -> None:
+        raise NotImplementedError
+
+    def _v2_project_edge(
+        self,
+        conn: sqlite3.Connection,
+        from_node: str,
+        to_node: str,
+        edge_type: str,
+        weight: float,
+        metadata_json: Optional[str],
+        *,
+        edge_id: Optional[str] = None,
+        created_at: Optional[str] = None,
+        strict: bool = False,
+        legacy_type: Optional[str] = None,
+    ) -> None:
+        raise NotImplementedError
+
+    def _v2_delete_nodes(self, conn: sqlite3.Connection, ids: Any) -> None:
+        raise NotImplementedError
+
+    def _v2_delete_edges_from(self, conn: sqlite3.Connection, node_id: str) -> None:
+        raise NotImplementedError
+
+    def _fts_match_ids(
+        self, conn: sqlite3.Connection, query: str, limit: int
+    ) -> List[str]:
+        raise NotImplementedError
+
+    # ── retrieval_reads.py: workspace scoping ────────────────────────────────
+    def filter_scoped_nodes(
+        self,
+        items: Any,
+        allowed_workspaces: Any,
+        *,
+        id_key: str = "id",
+        include_legacy_global: bool = False,
+    ) -> Any:
+        raise NotImplementedError
+
+    # ── documents.py: structured-document ingestion ──────────────────────────
+    def _document_structure(self, path: Path, ext: str) -> Dict[str, Any]:
+        raise NotImplementedError
+
+    def _ingest_structure_nodes(
+        self,
+        conn: sqlite3.Connection,
+        file_id: str,
+        filename: str,
+        structure: Dict[str, Any],
+        *,
+        owner: Optional[str] = None,
+        workspace_id: Optional[str] = None,
+    ) -> None:
+        raise NotImplementedError
+
+    # ── discovery.py / discovery_index.py: local filesystem indexing ─────────
+    def _iter_local_scan_entries(
+        self, root: Path, *, max_files: int
+    ) -> Iterable[Dict[str, Any]]:
+        raise NotImplementedError
+
+    def _local_file_decision(
+        self, path: Path, root: Path, stat: Any
+    ) -> Dict[str, Any]:
+        raise NotImplementedError
+
+    def _delete_local_file_graph(
+        self, conn: sqlite3.Connection, file_node_id: Optional[str]
+    ) -> None:
+        raise NotImplementedError
+
+    def _cleanup_local_graph_orphans(
+        self, conn: sqlite3.Connection, source_id: str
+    ) -> None:
+        raise NotImplementedError
+
+
+#: Every name a mixin may reach for through ``self``. Kept in sync by
+#: ``tests/unit/test_kg_contract.py`` — the test derives it from the class, so
+#: this constant cannot drift from the declarations above.
+KG_CORE_MEMBERS: Sequence[str] = tuple(
+    sorted(
+        name
+        for name in vars(KnowledgeGraphCore)
+        if not name.startswith("__")
+    )
+    + sorted(getattr(KnowledgeGraphCore, "__annotations__", {}))
+)
+
+
+__all__ = ["KG_CORE_MEMBERS", "KnowledgeGraphCore"]

package/lattice_brain/graph/_kg_fsutil.py

@@ -192,7 +192,7 @@ def _excluded_directory_reason(
     if os_type == "macos":
         home_library = Path.home() / "Library"
         try:
-            root_is_library = bool(root) and _is_relative_to(
+            root_is_library = root is not None and _is_relative_to(
                 root.expanduser().resolve(), home_library.expanduser().resolve()
             )
             if (

package/lattice_brain/graph/curator.py

@@ -525,7 +525,7 @@ def plan_concept_noise_reduction(
     remove: List[Dict[str, Any]] = []
     keep: List[Dict[str, Any]] = []
     for concept in concepts:
-        entry = {
+        entry: Dict[str, Any] = {
             "id": str(concept.get("id") or ""),
             "label": concept.get("label"),
             "df": int(concept.get("df") or 0),
@@ -534,7 +534,7 @@ def plan_concept_noise_reduction(
         if not entry["heuristic"]:
             keep.append({**entry, "reason": "user_created_protected"})
             continue
-        df = entry["df"]
+        df = int(entry["df"])
         if df < int(min_doc_frequency):
             df_ratio = (df / total) if total else 0.0
             remove.append({**entry, "df_ratio": round(df_ratio, 4), "reason": "below_frequency_floor"})
@@ -578,7 +578,7 @@ def plan_relation_noise_reduction(
     keep: List[Dict[str, Any]] = []
     demote: List[Dict[str, Any]] = []
     for edge in edges:
-        entry = {
+        entry: Dict[str, Any] = {
             "id": str(edge.get("id") or ""),
             "from": edge.get("from"),
             "to": edge.get("to"),
@@ -600,7 +600,7 @@ def plan_relation_noise_reduction(
         if not entry["evidence"]:
             keep.append({**entry, "reason": "unknown_evidence"})
             continue
-        if entry["weight"] < float(min_cooccurrence_weight):
+        if float(entry["weight"]) < float(min_cooccurrence_weight):
             demote.append({**entry, "reason": "weak_cooccurrence"})
             continue
         if degree > int(max_cooccurrence_degree):

package/lattice_brain/graph/discovery.py

@@ -1,12 +1,23 @@
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 from ..quiet import quiet
 
 # ruff: noqa: F403,F405
 from ._kg_common import *  # noqa: F403,F401
 
+# The cross-mixin surface (`_connect`, `_upsert_node`, …) is declared in
+# `_kg_contract.KnowledgeGraphCore`. It is a typing-only base: at runtime this
+# is `object`, so the MRO of `KnowledgeGraphStore` is unchanged.
+if TYPE_CHECKING:
+    from ._kg_contract import KnowledgeGraphCore as _Core
+else:
+    _Core = object
+
+
 
-class KnowledgeGraphDiscoveryMixin:
+class KnowledgeGraphDiscoveryMixin(_Core):
     def discover_local_roots(self) -> Dict[str, Any]:
         """Return safe, cross-platform starting points for structure browsing."""
         os_type = _current_os_type()

package/lattice_brain/graph/discovery_index.py

@@ -1,8 +1,19 @@
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 # ruff: noqa: F403,F405
 from ._kg_common import *  # noqa: F403,F401
 
+# The cross-mixin surface (`_connect`, `_upsert_node`, …) is declared in
+# `_kg_contract.KnowledgeGraphCore`. It is a typing-only base: at runtime this
+# is `object`, so the MRO of `KnowledgeGraphStore` is unchanged.
+if TYPE_CHECKING:
+    from ._kg_contract import KnowledgeGraphCore as _Core
+else:
+    _Core = object
+
+
 
 def _local_scoped_slug(prefix: str, value: str, workspace_id: Optional[str]) -> str:
     """Preserve legacy IDs while isolating newly workspace-scoped nodes."""
@@ -13,7 +24,7 @@ def _local_scoped_slug(prefix: str, value: str, workspace_id: Optional[str]) ->
     return f"{prefix}:{scope}:{slug}"
 
 
-class KnowledgeGraphLocalIndexMixin:
+class KnowledgeGraphLocalIndexMixin(_Core):
     """Local file → graph indexing (text extraction, node/index upserts,
     graph-node deletion, orphan cleanup, and the index_local_folder driver),
     split out of discovery. Composed into KnowledgeGraphStore alongside

package/lattice_brain/graph/documents.py

@@ -1,12 +1,23 @@
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 from ..quiet import quiet
 
 # ruff: noqa: F403,F405
 from ._kg_common import *  # noqa: F403,F401
 
+# The cross-mixin surface (`_connect`, `_upsert_node`, …) is declared in
+# `_kg_contract.KnowledgeGraphCore`. It is a typing-only base: at runtime this
+# is `object`, so the MRO of `KnowledgeGraphStore` is unchanged.
+if TYPE_CHECKING:
+    from ._kg_contract import KnowledgeGraphCore as _Core
+else:
+    _Core = object
+
+
 
-class KnowledgeGraphDocumentsMixin:
+class KnowledgeGraphDocumentsMixin(_Core):
     def find_documents_by_uri_prefix(self, prefix: str) -> List[Dict[str, Any]]:
         """Content nodes whose ``metadata.source_uri`` starts with ``prefix``.
 
@@ -246,7 +257,11 @@ class KnowledgeGraphDocumentsMixin:
 
             prs = Presentation(str(path))
             for slide_index, slide in enumerate(prs.slides, start=1):
-                slide_info = {"index": slide_index, "shapes": [], "texts": []}
+                slide_info: Dict[str, Any] = {
+                    "index": slide_index,
+                    "shapes": [],
+                    "texts": [],
+                }
                 for shape_index, shape in enumerate(slide.shapes, start=1):
                     shape_info = {
                         "index": shape_index,

package/lattice_brain/graph/ingest.py

@@ -1,11 +1,22 @@
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 from ..quiet import quiet
 from ..sensitivity import stamp_sensitivity
 
 # ruff: noqa: F403,F405
 from ._kg_common import *  # noqa: F403,F401
 
+# The cross-mixin surface (`_connect`, `_upsert_node`, …) is declared in
+# `_kg_contract.KnowledgeGraphCore`. It is a typing-only base: at runtime this
+# is `object`, so the MRO of `KnowledgeGraphStore` is unchanged.
+if TYPE_CHECKING:
+    from ._kg_contract import KnowledgeGraphCore as _Core
+else:
+    _Core = object
+
+
 
 def _scoped_slug_id(prefix: str, value: str, workspace_id: Optional[str]) -> str:
     """Keep legacy IDs unchanged while isolating every newly scoped identity."""
@@ -42,7 +53,7 @@ def _triple_edge_metadata(triple: Dict[str, Any]) -> Dict[str, Any]:
     return metadata
 
 
-class KnowledgeGraphIngestMixin:
+class KnowledgeGraphIngestMixin(_Core):
     def ingest_message(
         self,
         role: str,

package/lattice_brain/graph/proactive.py

@@ -191,11 +191,13 @@ class ProactiveBrain:
         for indices in token_index.values():
             if len(indices) < 2 or len(indices) > 50:  # skip too-common tokens
                 continue
-            for i, left in enumerate(indices):
-                for right in indices[i + 1:]:
-                    cooccur[(left, right)] = cooccur.get((left, right), 0) + 1
+            for i, left_idx in enumerate(indices):
+                for right_idx in indices[i + 1:]:
+                    cooccur[(left_idx, right_idx)] = (
+                        cooccur.get((left_idx, right_idx), 0) + 1
+                    )
 
-        near_pairs = []
+        near_pairs: List[Dict[str, Any]] = []
         for (li, ri), shared in sorted(cooccur.items(), key=lambda kv: -kv[1]):
             if shared < 3:
                 continue
@@ -219,7 +221,7 @@ class ProactiveBrain:
             )
             if len(near_pairs) >= max_pairs:
                 break
-        near_pairs.sort(key=lambda p: p["similarity"], reverse=True)
+        near_pairs.sort(key=lambda p: float(p["similarity"]), reverse=True)
 
         return {
             "nodes_scanned": len(nodes),
@@ -467,6 +469,8 @@ class ProactiveBrain:
             mode = "applied"
             for group in groups:
                 try:
+                    if merge_fn is None:  # guarded by apply_supported above
+                        raise RuntimeError("store has no merge_nodes")
                     result = merge_fn(group["keep"], group["remove"])
                     applied.append({"keep": group["keep"], "result": result})
                 except Exception as exc:  # keep going; report per-group failure

package/lattice_brain/graph/projection.py

@@ -1,10 +1,21 @@
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 from ..quiet import quiet
 
 # ruff: noqa: F403,F405
 from ._kg_common import *  # noqa: F403,F401
 
+# The cross-mixin surface (`_connect`, `_upsert_node`, …) is declared in
+# `_kg_contract.KnowledgeGraphCore`. It is a typing-only base: at runtime this
+# is `object`, so the MRO of `KnowledgeGraphStore` is unchanged.
+if TYPE_CHECKING:
+    from ._kg_contract import KnowledgeGraphCore as _Core
+else:
+    _Core = object
+
+
 # ── promotion review mode (review 2026-07-25 Wave 4) ─────────────────────────
 # When enabled, curate() parks would-be Topic promotions in graph_meta for a
 # human decision instead of writing them immediately. Explicit review_mode=
@@ -22,7 +33,7 @@ def _promotion_review_default() -> bool:
     return os.getenv(_PROMOTION_REVIEW_ENV, "").strip().lower() in ("1", "true", "yes")
 
 
-class KnowledgeGraphProjectionMixin:
+class KnowledgeGraphProjectionMixin(_Core):
     _FTS_SQL = """
         CREATE VIRTUAL TABLE IF NOT EXISTS node_fts USING fts5(
           node_id UNINDEXED, title, summary, metadata, tokenize='trigram'

package/lattice_brain/graph/provenance.py

@@ -1,10 +1,21 @@
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 # ruff: noqa: F403,F405
 from ._kg_common import *  # noqa: F403,F401
 
+# The cross-mixin surface (`_connect`, `_upsert_node`, …) is declared in
+# `_kg_contract.KnowledgeGraphCore`. It is a typing-only base: at runtime this
+# is `object`, so the MRO of `KnowledgeGraphStore` is unchanged.
+if TYPE_CHECKING:
+    from ._kg_contract import KnowledgeGraphCore as _Core
+else:
+    _Core = object
+
+
 
-class KnowledgeGraphProvenanceMixin:
+class KnowledgeGraphProvenanceMixin(_Core):
     def record_provenance(
         self,
         *,