ltcai 4.0.0 → 4.0.1

package/kg_schema.py

@@ -1,604 +1,3 @@
-"""
-Lattice AI — Knowledge Graph v2 schema (PPT spec aligned)
-=========================================================
+"""Compatibility shim for the v4 Knowledge Graph schema."""
 
-명세: ``lattice_ai_full_spec.pptx`` 슬라이드 20~22 (Node / Edge / Data Model)
-
-목적
-----
-기존 ``knowledge_graph.py`` 의 자유 문자열 노드/엣지 타입을 **명시 enum + SQLite v2
-스키마** 로 정식화한다. 이 모듈은 **스키마/초기화/프로젝션 지원** 역할만 담당한다:
-``NodeType``/``EdgeType`` taxonomy + legacy 정규화 매핑, ``nodes_v2``/``edges_v2``
-DDL(``SCHEMA_SQL``), 그리고 ``KGStoreV2``(스키마 init·heal·stats).
-
-실제 데이터 read/write 는 ``knowledge_graph.py`` 의 ``KnowledgeGraphStore`` 가
-legacy 테이블에 대한 dual-write 프로젝션(raw SQL) + ``kgv2_*`` 재구성 뷰로 수행한다.
-(과거의 native ``Node``/``Edge`` 모델과 ``KGStoreV2.upsert_*``/``get_node``/
-``search_*`` API 는 production 에서 쓰이지 않아 제거되었다.)
-
-설계 원칙
----------
-1. **기존 코드를 깨지 않는다**: 새 테이블 이름은 ``nodes_v2`` / ``edges_v2``
-   로 분리. 기존 ``nodes`` / ``edges`` 와 공존한다. legacy → v2 reprojection 은
-   ``knowledge_graph.py`` 의 버전 게이트 백필 한 곳에서만 수행한다.
-2. **정규화 + 무손실**: legacy 자유 문자열 타입은 ``NodeType``/``EdgeType``
-   superset 으로 정규화해 ``type`` 칼럼에 저장하고, 원본 문자열은 ``legacy_type``
-   칼럼에 그대로 보존한다. summary 와 metadata 는 ``attrs._kg`` 패스스루 blob 이
-   아니라 전용 ``summary`` 칼럼 / ``attrs``·``metadata`` 칼럼에 1급으로 저장한다.
-3. **표준 라이브러리만 사용**: 외부 의존성 없이 ``sqlite3`` 만으로 동작한다.
-4. **정규화 매핑은 명시적**: 한글 동사/legacy 라벨 → 영문 enum 표가 코드 안에
-   들어 있어서 어떤 옛 라벨이 어디로 매핑되는지 한눈에 보인다.
-
-사용 예
--------
-```python
-from kg_schema import KGStoreV2
-
-store = KGStoreV2("/Users/me/.ltcai/kg_v2.db")
-store.init_schema()        # nodes_v2 / edges_v2 생성 + 컬럼 drift self-heal
-print(store.stats())       # {"nodes": ..., "by_node_type": {...}, ...}
-```
-"""
-
-from __future__ import annotations
-
-import json
-import os
-import logging
-import sqlite3
-from contextlib import contextmanager
-from enum import Enum
-from typing import Any, Dict, Optional
-
-
-# ── Schema version ──────────────────────────────────────────────────────────
-KG_SCHEMA_V2_VERSION = 2
-EMBED_DIM = int(os.getenv("LATTICEAI_EMBED_DIM", "1024"))
-
-
-# ── Node / Edge taxonomy (PPT 슬라이드 20·21) ──────────────────────────────
-class NodeType(str, Enum):
-    """워크스페이스의 모든 ‘명사’.
-
-    PPT 슬라이드 20 카탈로그(상단 그룹)에 더해, ``knowledge_graph.py`` 가 실제로
-    써오던 legacy 자유 문자열 타입을 **무손실 superset**(하단 그룹)으로 1급 enum 화
-    한다. 덕분에 ``from_legacy`` 정규화가 의미를 잃지 않고(예: ``Computer`` →
-    ``COMPUTER``), 알 수 없는/동적(이벤트) 타입만 ``CONCEPT`` 로 폴백한다.
-    원본 문자열은 ``nodes_v2.legacy_type`` 에 그대로 보존되므로 정규화는 항상 무손실.
-    """
-    # PPT 슬라이드 20 정식 카탈로그
-    CONVERSATION = "CONVERSATION"   # 대화 세션 전체
-    MESSAGE      = "MESSAGE"        # 단일 발화
-    FILE         = "FILE"           # 업로드/연결된 파일
-    DOCUMENT     = "DOCUMENT"       # 생성/관리되는 문서 (보고서, 계획서 등)
-    CHUNK        = "CHUNK"          # 파일의 분할 청크
-    CODE_SYMBOL  = "CODE_SYMBOL"    # 함수·클래스·모듈
-    CONCEPT      = "CONCEPT"        # 추출된 개념 / 태그
-    PERSON       = "PERSON"         # 사용자·협업자
-    MODEL        = "MODEL"          # 로컬/원격 LLM
-    TOOL         = "TOOL"           # MCP 서버·외부 도구
-    PROJECT      = "PROJECT"        # 주제별 작업 공간
-    # legacy superset — knowledge_graph.py 가 실제로 생성하던 노드 타입들
-    COMPUTER     = "COMPUTER"       # 내 컴퓨터 (로컬 스캔 루트)
-    DRIVE        = "DRIVE"          # 드라이브 / 볼륨
-    FOLDER       = "FOLDER"         # 폴더
-    CODE_FILE    = "CODE_FILE"      # 코드 파일 (.py/.ts 등)
-    SPREADSHEET  = "SPREADSHEET"    # 엑셀 / CSV
-    SLIDE_DECK   = "SLIDE_DECK"     # 프레젠테이션
-    IMAGE        = "IMAGE"          # 이미지 파일
-    IMAGE_TEXT   = "IMAGE_TEXT"     # OCR 텍스트
-    SLIDE        = "SLIDE"          # 슬라이드 (덱의 한 장)
-    PAGE         = "PAGE"           # 페이지 (문서의 한 면)
-    SHEET        = "SHEET"          # 시트 (스프레드시트의 한 탭)
-    SECTION      = "SECTION"        # 문서 섹션
-    CHAT         = "CHAT"           # 대화 세션(채팅 UI)
-    AI_RESPONSE  = "AI_RESPONSE"    # 어시스턴트 발화
-    TOPIC        = "TOPIC"          # 주제 / 토픽
-    FEATURE      = "FEATURE"        # 소프트웨어 기능
-    TASK         = "TASK"           # 할 일
-    DECISION     = "DECISION"       # 결정 사항
-    ERROR        = "ERROR"          # 오류 / 버그
-    EVENT        = "EVENT"          # 분석/시스템 이벤트(동적 타입 폴백)
-    # v3.6.0 Knowledge Graph First — 모든 데이터 소스가 그래프로 수렴하기 위한
-    # 1급 엔티티. 추가형(additive)·확장 가능(extensible): 새 도메인 엔티티는
-    # 여기에 enum 멤버를 추가하고 _LEGACY_NODE_MAP 에 별칭만 등록하면 된다.
-    SOURCE       = "SOURCE"         # 수집 출처(파일/URL/브라우저 탭/git 등)의 출처 노드
-    REPOSITORY   = "REPOSITORY"     # git 저장소
-    MEETING      = "MEETING"        # 회의 / 미팅
-    ORGANIZATION = "ORGANIZATION"   # 조직 / 회사 / 팀
-    WORKFLOW     = "WORKFLOW"       # 워크플로우 정의/실행
-    AGENT        = "AGENT"          # 에이전트(역할/실행 주체)
-
-    @classmethod
-    def from_legacy(cls, label: str) -> "NodeType":
-        """legacy ``knowledge_graph.py`` 의 자유 문자열을 정식 enum 으로 정규화.
-
-        매핑이 없는(동적 이벤트 등) 타입은 ``CONCEPT`` 로 폴백하지만, 호출부는
-        원본 문자열을 ``legacy_type`` 칼럼에 별도 보존하므로 정보 손실은 없다.
-        """
-        m = (label or "").strip()
-        # Canonical values round-trip exactly (v4 native writes use them);
-        # without this, CODE_FILE/AI_RESPONSE etc. would degrade to CONCEPT.
-        try:
-            return cls(m.upper())
-        except ValueError:
-            pass
-        return _LEGACY_NODE_MAP.get(m.lower(), cls.CONCEPT)
-
-
-class EdgeType(str, Enum):
-    """노드 사이의 ‘방향성 있고 타입이 명시된’ 관계.  PPT 슬라이드 21."""
-    CONTAINS      = "CONTAINS"        # FILE → CHUNK
-    MENTIONS      = "MENTIONS"        # MESSAGE → CONCEPT
-    REFERENCES    = "REFERENCES"      # FILE → FILE / URL
-    REPLIES_TO    = "REPLIES_TO"      # MESSAGE → MESSAGE
-    AUTHORED_BY   = "AUTHORED_BY"     # FILE → PERSON
-    USES          = "USES"            # PROJECT → TOOL / MODEL
-    DERIVED_FROM  = "DERIVED_FROM"    # CHUNK → CHUNK (요약 등)
-    SIMILAR_TO    = "SIMILAR_TO"      # ANY ↔ ANY (의미 유사도)
-    DEPENDS_ON    = "DEPENDS_ON"      # CODE_SYMBOL → CODE_SYMBOL
-    TAGGED_AS     = "TAGGED_AS"       # ANY → CONCEPT
-    VERSION_OF    = "VERSION_OF"      # FILE → FILE (히스토리)
-    GRANTS_ACCESS = "GRANTS_ACCESS"   # PERSON → RESOURCE
-    USED_IN       = "USED_IN"         # CONCEPT → DOCUMENT (문서에 활용됨)
-    INSPIRED_BY   = "INSPIRED_BY"     # DOCUMENT → DOCUMENT (영감/참조 관계)
-    CONTRADICTS   = "CONTRADICTS"     # DOCUMENT ↔ DOCUMENT (상충 관계)
-    EVOLVES_FROM  = "EVOLVES_FROM"    # DOCUMENT → DOCUMENT (발전/개정 관계)
-    # legacy superset — knowledge_graph.py 가 실제로 생성하던 엣지 타입들
-    UPLOADED_BY    = "UPLOADED_BY"    # PERSON → FILE (업로드함)
-    WROTE          = "WROTE"          # PERSON → CONVERSATION (작성함)
-    HAS_EVENT      = "HAS_EVENT"      # CONVERSATION → EVENT (has_event)
-    TRIGGERED      = "TRIGGERED"      # PERSON → EVENT (triggered)
-    HAS_SLIDE      = "HAS_SLIDE"      # SLIDE_DECK → SLIDE (has_slide)
-    HAS_PAGE       = "HAS_PAGE"       # DOCUMENT → PAGE (has_page)
-    HAS_SHEET      = "HAS_SHEET"      # SPREADSHEET → SHEET (has_sheet)
-    HAS_CHUNK      = "HAS_CHUNK"      # FILE → CHUNK (has_chunk)
-    CONTAINS_IMAGE = "CONTAINS_IMAGE" # FILE → IMAGE (contains_image)
-    CONTAINS_SIGNAL = "CONTAINS_SIGNAL"  # NODE → CONCEPT (contains_signal)
-    DISCUSSES      = "DISCUSSES"      # SLIDE/PAGE → TOPIC (discusses)
-    IMPLIES        = "IMPLIES"        # NODE → NODE (implies)
-    RELATED_TO     = "RELATED_TO"     # ANY ↔ ANY (related_to)
-    # v3.6.0 Knowledge Graph First — 출처/소유/구성/결정 관계를 1급 엣지로 승격.
-    # 추가형: 새 관계는 enum 멤버 추가 + _LEGACY_EDGE_MAP 별칭 등록만으로 확장된다.
-    INDEXED_FROM       = "INDEXED_FROM"        # NODE → SOURCE (어떤 출처에서 색인됐는가)
-    MODIFIED_BY        = "MODIFIED_BY"         # NODE → PERSON (마지막 수정자)
-    BELONGS_TO_PROJECT = "BELONGS_TO_PROJECT"  # NODE → PROJECT
-    PART_OF            = "PART_OF"             # NODE → NODE (구성요소 관계)
-    DISCUSSED_IN       = "DISCUSSED_IN"        # CONCEPT/DECISION → MEETING/CHAT
-    DECIDED_BY         = "DECIDED_BY"          # DECISION → PERSON
-    GENERATED_BY       = "GENERATED_BY"        # NODE → AGENT/MODEL/WORKFLOW
-    USED_BY_AGENT      = "USED_BY_AGENT"       # NODE → AGENT (에이전트가 사용함)
-
-    @classmethod
-    def from_legacy(cls, label: str) -> "EdgeType":
-        """legacy 자유 문자열/한글 동사를 정식 enum 으로 정규화.
-
-        매핑이 없는 동적 타입은 ``MENTIONS`` 로 폴백하지만, 호출부는 원본 문자열을
-        ``edges_v2.legacy_type`` 에 보존하므로 정보 손실은 없다.
-        """
-        m = (label or "").strip()
-        # Canonical values round-trip exactly (v4 native writes use them).
-        try:
-            return cls(m.upper())
-        except ValueError:
-            pass
-        return _LEGACY_EDGE_MAP.get(m.lower(), cls.MENTIONS)
-
-
-# legacy(자유 문자열 / 한글 동사) → enum 매핑 표.
-# superset 정규화: 알려진 legacy 타입은 1:1 의미 보존 매핑, 미지/동적 타입만 폴백.
-_LEGACY_NODE_MAP: Dict[str, NodeType] = {
-    "conversation": NodeType.CONVERSATION,
-    "chat":         NodeType.CHAT,
-    "message":      NodeType.MESSAGE,
-    "airesponse":   NodeType.AI_RESPONSE,
-    "file":         NodeType.FILE,
-    "codefile":     NodeType.CODE_FILE,
-    "spreadsheet":  NodeType.SPREADSHEET,
-    "slidedeck":    NodeType.SLIDE_DECK,
-    "image":        NodeType.IMAGE,
-    "imagetext":    NodeType.IMAGE_TEXT,
-    "computer":     NodeType.COMPUTER,
-    "drive":        NodeType.DRIVE,
-    "folder":       NodeType.FOLDER,
-    "page":         NodeType.PAGE,
-    "sheet":        NodeType.SHEET,
-    "slide":        NodeType.SLIDE,
-    "section":      NodeType.SECTION,
-    "chunk":        NodeType.CHUNK,
-    "code":         NodeType.CODE_SYMBOL,
-    "concept":      NodeType.CONCEPT,
-    "topic":        NodeType.TOPIC,
-    "feature":      NodeType.FEATURE,
-    "task":         NodeType.TASK,
-    "decision":     NodeType.DECISION,
-    "error":        NodeType.ERROR,
-    "event":        NodeType.EVENT,
-    "tag":          NodeType.CONCEPT,
-    "person":       NodeType.PERSON,
-    "user":         NodeType.PERSON,
-    "model":        NodeType.MODEL,
-    "tool":         NodeType.TOOL,
-    "mcp":          NodeType.TOOL,
-    "project":      NodeType.PROJECT,
-    "workspace":    NodeType.PROJECT,
-    "document":     NodeType.DOCUMENT,
-    "report":       NodeType.DOCUMENT,
-    "plan":         NodeType.DOCUMENT,
-    "proposal":     NodeType.DOCUMENT,
-    "보고서":       NodeType.DOCUMENT,
-    "계획서":       NodeType.DOCUMENT,
-    "기획서":       NodeType.DOCUMENT,
-    # v3.6.0 Knowledge Graph First 엔티티
-    "source":       NodeType.SOURCE,
-    "ingestionsource": NodeType.SOURCE,
-    "repository":   NodeType.REPOSITORY,
-    "repo":         NodeType.REPOSITORY,
-    "gitrepo":      NodeType.REPOSITORY,
-    "meeting":      NodeType.MEETING,
-    "organization": NodeType.ORGANIZATION,
-    "org":          NodeType.ORGANIZATION,
-    "company":      NodeType.ORGANIZATION,
-    "team":         NodeType.ORGANIZATION,
-    "workflow":     NodeType.WORKFLOW,
-    "agent":        NodeType.AGENT,
-}
-
-_LEGACY_EDGE_MAP: Dict[str, EdgeType] = {
-    # 한글 동사 (knowledge_graph.py 의 EDGE_VERB)
-    "언급함": EdgeType.MENTIONS,
-    "포함함": EdgeType.CONTAINS,
-    "해결함": EdgeType.REFERENCES,
-    "의존함": EdgeType.DEPENDS_ON,
-    "설명함": EdgeType.MENTIONS,
-    "비교함": EdgeType.SIMILAR_TO,
-    "사용함": EdgeType.USES,
-    "연결함": EdgeType.REFERENCES,
-    "확장함": EdgeType.DERIVED_FROM,
-    "생성함": EdgeType.AUTHORED_BY,
-    "작성함": EdgeType.WROTE,
-    "업로드함": EdgeType.UPLOADED_BY,
-    "대체함": EdgeType.VERSION_OF,
-    "지원함": EdgeType.USES,
-    "발생함": EdgeType.REFERENCES,
-    "관련됨": EdgeType.MENTIONS,
-    # 영문 별칭
-    "mentions": EdgeType.MENTIONS,
-    "contains": EdgeType.CONTAINS,
-    "references": EdgeType.REFERENCES,
-    "replies_to": EdgeType.REPLIES_TO,
-    "authored_by": EdgeType.AUTHORED_BY,
-    "uses": EdgeType.USES,
-    "derived_from": EdgeType.DERIVED_FROM,
-    "similar_to": EdgeType.SIMILAR_TO,
-    "depends_on": EdgeType.DEPENDS_ON,
-    "tagged_as": EdgeType.TAGGED_AS,
-    "version_of": EdgeType.VERSION_OF,
-    "grants_access": EdgeType.GRANTS_ACCESS,
-    "used_in":       EdgeType.USED_IN,
-    "inspired_by":   EdgeType.INSPIRED_BY,
-    "contradicts":   EdgeType.CONTRADICTS,
-    "evolves_from":  EdgeType.EVOLVES_FROM,
-    # legacy superset 별칭 (knowledge_graph.py 가 실제로 쓰던 엣지 타입)
-    "uploaded_by":     EdgeType.UPLOADED_BY,
-    "wrote":           EdgeType.WROTE,
-    "has_event":       EdgeType.HAS_EVENT,
-    "triggered":       EdgeType.TRIGGERED,
-    "has_slide":       EdgeType.HAS_SLIDE,
-    "has_page":        EdgeType.HAS_PAGE,
-    "has_sheet":       EdgeType.HAS_SHEET,
-    "has_chunk":       EdgeType.HAS_CHUNK,
-    "contains_image":  EdgeType.CONTAINS_IMAGE,
-    "contains_signal": EdgeType.CONTAINS_SIGNAL,
-    "discusses":       EdgeType.DISCUSSES,
-    "implies":         EdgeType.IMPLIES,
-    "related_to":      EdgeType.RELATED_TO,
-    "활용됨":        EdgeType.USED_IN,
-    "영감받음":      EdgeType.INSPIRED_BY,
-    "상충함":        EdgeType.CONTRADICTS,
-    "발전함":        EdgeType.EVOLVES_FROM,
-    # v3.6.0 Knowledge Graph First 관계
-    "indexed_from":       EdgeType.INDEXED_FROM,
-    "modified_by":        EdgeType.MODIFIED_BY,
-    "belongs_to_project": EdgeType.BELONGS_TO_PROJECT,
-    "belongs_to":         EdgeType.BELONGS_TO_PROJECT,
-    "part_of":            EdgeType.PART_OF,
-    "discussed_in":       EdgeType.DISCUSSED_IN,
-    "decided_by":         EdgeType.DECIDED_BY,
-    "generated_by":       EdgeType.GENERATED_BY,
-    "used_by_agent":      EdgeType.USED_BY_AGENT,
-    "색인됨":             EdgeType.INDEXED_FROM,
-    "수정함":             EdgeType.MODIFIED_BY,
-    "결정함":             EdgeType.DECIDED_BY,
-    "구성요소":           EdgeType.PART_OF,
-}
-
-# ── SQLite v2 store ─────────────────────────────────────────────────────────
-SCHEMA_SQL = """
-CREATE TABLE IF NOT EXISTS kg_meta (
-  key   TEXT PRIMARY KEY,
-  value TEXT NOT NULL
-);
-
-CREATE TABLE IF NOT EXISTS nodes_v2 (
-  id               TEXT PRIMARY KEY,
-  type             TEXT NOT NULL,
-  legacy_type      TEXT,
-  label            TEXT NOT NULL,
-  summary          TEXT,
-  attrs            TEXT NOT NULL DEFAULT '{}',
-  embedding        BLOB,
-  owner_id         TEXT,
-  -- NULL workspace_id = legacy-global (pre-scoping rows, readable machine-wide).
-  workspace_id     TEXT,
-  -- 'legacy' marks rows that predate scoping — the 'private' default must not
-  -- silently privatize previously machine-shared data (design-review ruling).
-  visibility       TEXT NOT NULL DEFAULT 'private',
-  -- Revision chain: a node replaced by a newer one points at its successor.
-  superseded_by    TEXT,
-  created_at       TEXT NOT NULL,
-  updated_at       TEXT NOT NULL,
-  style            TEXT,
-  tone             TEXT,
-  importance_score REAL NOT NULL DEFAULT 0.0,
-  last_used        TEXT
-);
-
-CREATE TABLE IF NOT EXISTS edges_v2 (
-  id           TEXT PRIMARY KEY,
-  source       TEXT NOT NULL,
-  target       TEXT NOT NULL,
-  type         TEXT NOT NULL,
-  legacy_type  TEXT NOT NULL DEFAULT '',
-  weight       REAL NOT NULL DEFAULT 1.0,
-  confidence   REAL NOT NULL DEFAULT 1.0,
-  evidence     TEXT NOT NULL DEFAULT '[]',
-  metadata     TEXT NOT NULL DEFAULT '{}',
-  created_by   TEXT NOT NULL DEFAULT 'user',
-  created_at   TEXT NOT NULL,
-  -- Edge identity (v4): the normalized type AND the raw legacy type.
-  -- Migrated rows keep their legacy_type discriminator, so two distinct
-  -- legacy strings between one pair (e.g. "mentions" / "관련됨") stay
-  -- distinct even though both normalize to MENTIONS. Native canonical
-  -- writes carry legacy_type='' so their identity is effectively
-  -- (source, target, type) — two canonical types between the same pair
-  -- (e.g. MENTIONS + CONTAINS) never collide. The pre-v4
-  -- UNIQUE(source, target, legacy_type) would have silently merged them.
-  UNIQUE(source, target, type, legacy_type),
-  FOREIGN KEY(source) REFERENCES nodes_v2(id) ON DELETE CASCADE,
-  FOREIGN KEY(target) REFERENCES nodes_v2(id) ON DELETE CASCADE
-);
-
--- Temporal dimension (v4): every repeated observation of a relationship is
--- recorded — edges_v2's UNIQUE identity + weight=max would otherwise erase
--- when something was learned, how often, and whether it still holds.
-CREATE TABLE IF NOT EXISTS edge_occurrences (
-  id          INTEGER PRIMARY KEY AUTOINCREMENT,
-  edge_id     TEXT NOT NULL,
-  observed_at TEXT NOT NULL,
-  weight      REAL NOT NULL DEFAULT 1.0,
-  source      TEXT,
-  FOREIGN KEY(edge_id) REFERENCES edges_v2(id) ON DELETE CASCADE
-);
-CREATE INDEX IF NOT EXISTS idx_edge_occurrences_edge ON edge_occurrences(edge_id);
-CREATE INDEX IF NOT EXISTS idx_edge_occurrences_time ON edge_occurrences(observed_at);
-
-CREATE INDEX IF NOT EXISTS idx_nodes_v2_type     ON nodes_v2(type);
-CREATE INDEX IF NOT EXISTS idx_nodes_v2_legacy   ON nodes_v2(legacy_type);
-CREATE INDEX IF NOT EXISTS idx_nodes_v2_owner    ON nodes_v2(owner_id);
-CREATE INDEX IF NOT EXISTS idx_edges_v2_source   ON edges_v2(source);
-CREATE INDEX IF NOT EXISTS idx_edges_v2_target   ON edges_v2(target);
-CREATE INDEX IF NOT EXISTS idx_edges_v2_type     ON edges_v2(type);
-CREATE INDEX IF NOT EXISTS idx_edges_v2_legacy   ON edges_v2(legacy_type);
-"""
-
-
-def _exec_script(conn: sqlite3.Connection, script: str) -> None:
-    """Run a multi-statement SQL script on ``conn`` statement-by-statement.
-
-    Unlike ``sqlite3.Connection.executescript``, this does NOT issue an implicit
-    COMMIT before running, so the statements join the caller's open transaction.
-    Safe for our schema/view DDL (no ``;`` inside string literals).
-    """
-    for stmt in script.split(";"):
-        s = stmt.strip()
-        if s:
-            conn.execute(s)
-
-
-class KGStoreV2:
-    """가벼운 SQLite 기반 v2 스토어 — **스키마/초기화 지원 전용**.
-
-    ``init_schema`` 으로 ``nodes_v2``/``edges_v2`` 를 생성·heal 하고 ``stats`` 로
-    집계를 노출한다. 데이터 read/write 는 ``knowledge_graph.KnowledgeGraphStore``
-    프로젝션이 담당하므로 native upsert/get/search API 는 두지 않는다.
-    """
-
-    def __init__(self, db_path: str):
-        self.db_path = db_path
-
-    @contextmanager
-    def _conn(self):
-        conn = sqlite3.connect(self.db_path)
-        conn.row_factory = sqlite3.Row
-        conn.execute("PRAGMA foreign_keys = ON")
-        try:
-            yield conn
-            conn.commit()
-        finally:
-            conn.close()
-
-    # Columns the current code writes; used to detect schema-evolution drift in
-    # v2 tables that an older ``CREATE TABLE IF NOT EXISTS`` left behind.
-    _V2_EXPECTED_COLUMNS = {
-        "edges_v2": {"id", "source", "target", "type", "legacy_type", "weight",
-                     "confidence", "evidence", "metadata", "created_by", "created_at"},
-        "nodes_v2": {"id", "type", "legacy_type", "label", "summary", "attrs",
-                     "embedding", "owner_id", "workspace_id", "visibility",
-                     "superseded_by", "created_at", "updated_at", "style",
-                     "tone", "importance_score", "last_used"},
-    }
-
-    # Columns added after a table's first release that can be healed in place
-    # with ALTER TABLE ADD COLUMN (nullable / defaulted only).
-    _V2_ADDABLE_COLUMNS = {
-        "nodes_v2": {"workspace_id": "TEXT", "superseded_by": "TEXT"},
-        "edges_v2": {},
-    }
-
-    def _drop_stale_empty_v2_tables(self, conn: sqlite3.Connection) -> None:
-        """Drop v2 tables that predate a schema change — but only when empty.
-
-        ``CREATE TABLE IF NOT EXISTS`` never upgrades an existing table, so a
-        v2 table created by an older version keeps its old columns and breaks
-        inserts. Recreating is safe precisely because these tables have never
-        held data (the v2 read-path isn't wired yet); we refuse to drop any
-        table that contains rows.
-        """
-        # edges_v2 first (it has FKs into nodes_v2)
-        for table in ("edges_v2", "nodes_v2"):
-            exists = conn.execute(
-                "SELECT 1 FROM sqlite_master WHERE type='table' AND name=?", (table,)
-            ).fetchone()
-            if not exists:
-                continue
-            cols = {r[1] for r in conn.execute(f"PRAGMA table_info({table})").fetchall()}
-            missing = self._V2_EXPECTED_COLUMNS[table] - cols
-            if not missing:
-                continue
-            # Additive columns heal in place without touching data.
-            addable = self._V2_ADDABLE_COLUMNS.get(table, {})
-            for col in sorted(missing & set(addable)):
-                conn.execute(f"ALTER TABLE {table} ADD COLUMN {col} {addable[col]}")
-            missing -= set(addable)
-            if not missing:
-                continue
-            count = conn.execute(f"SELECT COUNT(*) FROM {table}").fetchone()[0]
-            if count == 0:
-                conn.execute(f"DROP TABLE {table}")
-            else:
-                logging.warning(
-                    "kg_schema: %s is missing columns %s but holds %d rows — "
-                    "leaving it untouched (manual migration required).",
-                    table, sorted(missing), count,
-                )
-
-    def init_schema(self, conn: Optional[sqlite3.Connection] = None) -> None:
-        """Create the v2 schema and record metadata.
-
-        Pass ``conn`` to run inside the caller's open transaction (used by the
-        atomic knowledge_graph migration); otherwise a private connection is
-        opened and committed. Uses ``_exec_script`` rather than
-        ``executescript`` so it never force-commits the caller's transaction.
-        """
-        if conn is not None:
-            self._init_schema_on(conn)
-            return
-        with self._conn() as own:
-            self._init_schema_on(own)
-
-    def _rebuild_edges_identity(self, conn: sqlite3.Connection) -> None:
-        """Migrate edges_v2 from the pre-v4 UNIQUE(source, target, legacy_type)
-        identity to UNIQUE(source, target, type, legacy_type).
-
-        SQLite cannot alter constraints, so this is a create→copy→swap inside
-        the caller's transaction. Data-preserving: every existing row keeps its
-        legacy_type discriminator. Re-entrant: keyed on the actual constraint
-        in sqlite_master, not a one-time stamp.
-        """
-        row = conn.execute(
-            "SELECT sql FROM sqlite_master WHERE type='table' AND name='edges_v2'"
-        ).fetchone()
-        if not row or "UNIQUE(source, target, type, legacy_type)" in (row["sql"] or ""):
-            return
-        conn.execute("ALTER TABLE edges_v2 RENAME TO edges_v2_old")
-        # Recreate from the canonical DDL (edges_v2 portion of SCHEMA_SQL).
-        start = SCHEMA_SQL.index("CREATE TABLE IF NOT EXISTS edges_v2")
-        end = SCHEMA_SQL.index(");", start) + 2
-        conn.execute(SCHEMA_SQL[start:end].rstrip(";"))
-        conn.execute(
-            """
-            INSERT INTO edges_v2 (id, source, target, type, legacy_type, weight,
-                                  confidence, evidence, metadata, created_by, created_at)
-            SELECT id, source, target, type, legacy_type, weight,
-                   confidence, evidence, metadata, created_by, created_at
-            FROM edges_v2_old
-            """
-        )
-        conn.execute("DROP TABLE edges_v2_old")
-        logging.info("kg_schema: rebuilt edges_v2 with (source, target, type, legacy_type) identity")
-
-    def _init_schema_on(self, conn: sqlite3.Connection) -> None:
-        self._drop_stale_empty_v2_tables(conn)
-        self._rebuild_edges_identity(conn)
-        _exec_script(conn, SCHEMA_SQL)
-        conn.execute(
-            "INSERT OR REPLACE INTO kg_meta(key, value) VALUES (?, ?)",
-            ("schema_version", str(KG_SCHEMA_V2_VERSION)),
-        )
-        conn.execute(
-            "INSERT OR REPLACE INTO kg_meta(key, value) VALUES (?, ?)",
-            ("embed_dim", str(EMBED_DIM)),
-        )
-
-    # ── Maintenance ──────────────────────────────────────────
-    def stats(self) -> Dict[str, Any]:
-        with self._conn() as conn:
-            n_nodes = conn.execute("SELECT COUNT(*) FROM nodes_v2").fetchone()[0]
-            n_edges = conn.execute("SELECT COUNT(*) FROM edges_v2").fetchone()[0]
-            per_type = {
-                r["type"]: r["c"]
-                for r in conn.execute(
-                    "SELECT type, COUNT(*) AS c FROM nodes_v2 GROUP BY type"
-                ).fetchall()
-            }
-            per_edge = {
-                r["type"]: r["c"]
-                for r in conn.execute(
-                    "SELECT type, COUNT(*) AS c FROM edges_v2 GROUP BY type"
-                ).fetchall()
-            }
-        return {
-            "schema_version": KG_SCHEMA_V2_VERSION,
-            "embed_dim":      EMBED_DIM,
-            "nodes":          n_nodes,
-            "edges":          n_edges,
-            "by_node_type":   per_type,
-            "by_edge_type":   per_edge,
-        }
-
-
-# NOTE: legacy → v2 reprojection lives in ``knowledge_graph.py``
-# (``KnowledgeGraphStore._backfill_v2_if_needed`` / ``_v2_project_node``/_edge),
-# which is the single live, version-gated migration path. The old standalone
-# ``migrate_legacy_to_v2()`` helper + CLI ``migrate`` subcommand were removed as
-# dead code (no callers); the normalized projection now writes the first-class
-# ``legacy_type``/``summary``/``metadata`` columns directly.
-
-
-# ── CLI ────────────────────────────────────────────────────────────────────
-def _cli() -> int:
-    import argparse
-    p = argparse.ArgumentParser(prog="kg_schema",
-                                description="Lattice AI KG v2 utilities")
-    sub = p.add_subparsers(dest="cmd", required=True)
-
-    sub_init = sub.add_parser("init", help="initialize v2 schema in a DB")
-    sub_init.add_argument("db", help="path to sqlite db")
-
-    sub_stats = sub.add_parser("stats", help="print store statistics")
-    sub_stats.add_argument("db", help="path to sqlite db")
-
-    args = p.parse_args()
-    if args.cmd == "init":
-        KGStoreV2(args.db).init_schema()
-        print(f"initialized v2 schema in {args.db}")
-        return 0
-    if args.cmd == "stats":
-        print(json.dumps(KGStoreV2(args.db).stats(), indent=2, ensure_ascii=False))
-        return 0
-    return 2
-
-
-if __name__ == "__main__":
-    raise SystemExit(_cli())
+from latticeai.brain.schema import *  # noqa: F403,F401