ltcai 0.5.0 → 0.5.1

package/docs/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## [0.5.1] - 2026-05-31
+
+> KGStoreV2 정규화 스키마 + 마이그레이션 하드닝 + native API 정리(릴리스).
+
+### Changed
+
+- **KGStoreV2 정규화 스키마** — `attrs._kg` 패스스루 제거. legacy 자유문자열
+  노드/엣지 타입을 무손실 `NodeType`/`EdgeType` superset으로 정규화해 `type`에
+  저장하고 원본은 신규 `legacy_type` 칼럼에 보존. summary/metadata는 1급 칼럼으로
+  승격. 엣지 정체성은 `(source,target,legacy_type)`로 키잉해 정규화 충돌로 인한
+  엣지 소실 방지. `kgv2_*` 재구성 뷰가 legacy read를 byte-identical하게 유지.
+- **마이그레이션 하드닝** — `_init_v2_schema`의 DROP→CREATE→VIEWS→BACKFILL→
+  version-stamp 전 과정을 단일 트랜잭션(`BEGIN` + statement 단위 `_exec_script`)으로
+  원자화. 중간 실패 시 전부 롤백되어 이전 프로젝션·`projection_version` 보존, 다음
+  기동에서 재시도. 마이그레이션은 권위적 legacy `nodes`/`edges`를 절대 건드리지
+  않음. 프로젝션은 legacy `title`/`summary`/`metadata_json`을 verbatim 저장해
+  byte-faithful(절단·키 재정렬 제거, NULL summary round-trip).
+- **KGStoreV2 native API 정리** — production 미사용인 native 데이터 API
+  (`upsert_node`/`upsert_edge`/`get_node`/`list_nodes`/`neighbors`/`search_similar`)와
+  `Node`/`Edge`/`Visibility` 모델, 관련 헬퍼(`validate_endpoints`,
+  `EDGE_ENDPOINT_RULES`, `encode/decode_embedding`, `cosine`, row→model 변환)를
+  제거. `KGStoreV2`는 스키마/초기화/heal/stats 지원 역할만 유지. `kg_schema.py`
+  ~870→475줄. `test_document_generation`의 직접 `KGStoreV2` 의존을 제거하고
+  스키마/production 경로 검증으로 전환.
+
+### Removed
+
+- dead code: `migrate_legacy_to_v2()` 및 관련 헬퍼/CLI `migrate` 서브커맨드,
+  native KGStoreV2 데이터 API 및 모델, 미사용 import(`struct`/`uuid`/`dataclasses`
+  /`datetime` 등).
+
+### Internal
+
+- dual-write 불변식 런타임 진단 `_v2_sync_report()` 추가. 단위 테스트 192 통과.
+
 ## [0.5.0] - 2026-05-31
 
 > MLX 샘플링 API 호환성 버그 수정 + 릴리스 워크플로 build-only 전환.

package/kg_schema.py

@@ -6,51 +6,37 @@ Lattice AI — Knowledge Graph v2 schema (PPT spec aligned)
 
 목적
 ----
-기존 ``knowledge_graph.py`` 의 자유 문자열 노드/엣지 타입을 **명시 enum + Pydantic
-모델 + SQLite v2 스키마** 로 정식화한다. embedding · confidence · evidence ·
-owner/visibility · createdBy 필드를 1급 시민으로 승격해서, semantic search
-(SIMILAR_TO 엣지 추론) 와 multi-tenant 권한 모델의 기반을 만든다.
+기존 ``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`` 와 공존한다. 마이그레이션은 별도
-   유틸리티(`migrate_legacy_to_v2()`) 로 수행.
-2. **표준 라이브러리만 사용**: Pydantic 이 없는 환경에서도 dataclass 로
-   동작하도록 ``from dataclasses import dataclass`` 를 사용한다.
-   타입 검증은 ``validate()`` 메서드에서 수동.
-3. **embedding 은 옵셔널이지만 권장**: 차원은 환경 변수
-   ``LATTICEAI_EMBED_DIM`` (기본 1024). bytes blob 으로 저장.
-4. **마이그레이션 매핑은 명시적**: 한글 동사 → 영문 enum 표가 코드 안에 들어
-   있어서 어떤 옛 라벨이 어디로 매핑되는지 한눈에 보인다.
+   로 분리. 기존 ``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, Node, Edge, NodeType, EdgeType,
-)
+from kg_schema import KGStoreV2
 
 store = KGStoreV2("/Users/me/.ltcai/kg_v2.db")
-store.init_schema()
-
-n1 = Node(
-    type=NodeType.FILE,
-    label="LatticeAI_기획서.pdf",
-    attrs={"mime": "application/pdf", "pageCount": 24, "lang": "ko"},
-    owner_id="user_seoljun",
-)
-n2 = Node(type=NodeType.CONCEPT, label="MCP")
-store.upsert_node(n1)
-store.upsert_node(n2)
-
-store.upsert_edge(Edge(
-    source=n1.id, target=n2.id,
-    type=EdgeType.MENTIONS,
-    weight=0.82, confidence=0.91,
-    evidence=["chunk:01HX7K…#p3", "chunk:01HX7K…#p11"],
-    created_by="extractor:llm-gemma-3-12b",
-))
+store.init_schema()        # nodes_v2 / edges_v2 생성 + 컬럼 drift self-heal
+print(store.stats())       # {"nodes": ..., "by_node_type": {...}, ...}
 ```
 """
 
@@ -58,17 +44,11 @@ from __future__ import annotations
 
 import json
 import os
-import re
 import logging
 import sqlite3
-import struct
-import time
-import uuid
 from contextlib import contextmanager
-from dataclasses import dataclass, field, asdict
-from datetime import datetime, timezone
 from enum import Enum
-from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple
+from typing import Any, Dict, Optional
 
 
 # ── Schema version ──────────────────────────────────────────────────────────
@@ -78,7 +58,15 @@ EMBED_DIM = int(os.getenv("LATTICEAI_EMBED_DIM", "1024"))
 
 # ── Node / Edge taxonomy (PPT 슬라이드 20·21) ──────────────────────────────
 class NodeType(str, Enum):
-    """워크스페이스의 모든 ‘명사’.  PPT 슬라이드 20 카탈로그."""
+    """워크스페이스의 모든 ‘명사’.
+
+    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"           # 업로드/연결된 파일
@@ -90,10 +78,35 @@ class NodeType(str, Enum):
     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"          # 분석/시스템 이벤트(동적 타입 폴백)
 
     @classmethod
     def from_legacy(cls, label: str) -> "NodeType":
-        """legacy ``knowledge_graph.py`` 의 자유 문자열을 정식 enum 으로."""
+        """legacy ``knowledge_graph.py`` 의 자유 문자열을 정식 enum 으로 정규화.
+
+        매핑이 없는(동적 이벤트 등) 타입은 ``CONCEPT`` 로 폴백하지만, 호출부는
+        원본 문자열을 ``legacy_type`` 칼럼에 별도 보존하므로 정보 손실은 없다.
+        """
         m = (label or "").strip().lower()
         return _LEGACY_NODE_MAP.get(m, cls.CONCEPT)
 
@@ -116,28 +129,61 @@ class EdgeType(str, Enum):
     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)
 
     @classmethod
     def from_legacy(cls, label: str) -> "EdgeType":
+        """legacy 자유 문자열/한글 동사를 정식 enum 으로 정규화.
+
+        매핑이 없는 동적 타입은 ``MENTIONS`` 로 폴백하지만, 호출부는 원본 문자열을
+        ``edges_v2.legacy_type`` 에 보존하므로 정보 손실은 없다.
+        """
         m = (label or "").strip().lower()
         return _LEGACY_EDGE_MAP.get(m, cls.MENTIONS)
 
 
-# legacy(자유 문자열 / 한글 동사) → enum 매핑 표
+# legacy(자유 문자열 / 한글 동사) → enum 매핑 표.
+# superset 정규화: 알려진 legacy 타입은 1:1 의미 보존 매핑, 미지/동적 타입만 폴백.
 _LEGACY_NODE_MAP: Dict[str, NodeType] = {
     "conversation": NodeType.CONVERSATION,
+    "chat":         NodeType.CHAT,
     "message":      NodeType.MESSAGE,
-    "airesponse":   NodeType.MESSAGE,
+    "airesponse":   NodeType.AI_RESPONSE,
     "file":         NodeType.FILE,
-    "document":     NodeType.FILE,
-    "page":         NodeType.CHUNK,
-    "sheet":        NodeType.CHUNK,
-    "slide":        NodeType.CHUNK,
+    "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,
-    "feature":      NodeType.CONCEPT,
-    "error":        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,
@@ -167,6 +213,8 @@ _LEGACY_EDGE_MAP: Dict[str, EdgeType] = {
     "연결함": EdgeType.REFERENCES,
     "확장함": EdgeType.DERIVED_FROM,
     "생성함": EdgeType.AUTHORED_BY,
+    "작성함": EdgeType.WROTE,
+    "업로드함": EdgeType.UPLOADED_BY,
     "대체함": EdgeType.VERSION_OF,
     "지원함": EdgeType.USES,
     "발생함": EdgeType.REFERENCES,
@@ -188,189 +236,26 @@ _LEGACY_EDGE_MAP: Dict[str, EdgeType] = {
     "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,
 }
 
-# 노드 타입별로 허용되는 source / target 조합 (PPT 카탈로그 그대로)
-# None == 모든 타입 허용
-EDGE_ENDPOINT_RULES: Dict[EdgeType, Tuple[Optional[Sequence[NodeType]], Optional[Sequence[NodeType]]]] = {
-    EdgeType.CONTAINS:      ((NodeType.FILE, NodeType.DOCUMENT),
-                             (NodeType.CHUNK,)),
-    EdgeType.MENTIONS:      ((NodeType.MESSAGE, NodeType.FILE, NodeType.CHUNK, NodeType.DOCUMENT),
-                             (NodeType.CONCEPT, NodeType.PERSON, NodeType.MODEL, NodeType.TOOL)),
-    EdgeType.REFERENCES:    ((NodeType.FILE, NodeType.MESSAGE, NodeType.CHUNK),
-                             (NodeType.FILE, NodeType.MESSAGE, NodeType.CHUNK)),
-    EdgeType.REPLIES_TO:    ((NodeType.MESSAGE,),         (NodeType.MESSAGE,)),
-    EdgeType.AUTHORED_BY:   ((NodeType.FILE, NodeType.MESSAGE, NodeType.CONVERSATION, NodeType.DOCUMENT),
-                             (NodeType.PERSON,)),
-    EdgeType.USES:          ((NodeType.PROJECT, NodeType.CONVERSATION),
-                             (NodeType.TOOL, NodeType.MODEL)),
-    EdgeType.DERIVED_FROM:  ((NodeType.CHUNK, NodeType.FILE),
-                             (NodeType.CHUNK, NodeType.FILE)),
-    EdgeType.SIMILAR_TO:    (None, None),
-    EdgeType.DEPENDS_ON:    ((NodeType.CODE_SYMBOL,), (NodeType.CODE_SYMBOL,)),
-    EdgeType.TAGGED_AS:     (None, (NodeType.CONCEPT,)),
-    EdgeType.VERSION_OF:    ((NodeType.FILE,), (NodeType.FILE,)),
-    EdgeType.GRANTS_ACCESS: ((NodeType.PERSON,),
-                             (NodeType.FILE, NodeType.CONVERSATION, NodeType.PROJECT)),
-    EdgeType.USED_IN:       ((NodeType.CONCEPT,),
-                             (NodeType.DOCUMENT, NodeType.FILE)),
-    EdgeType.INSPIRED_BY:   ((NodeType.DOCUMENT, NodeType.FILE),
-                             (NodeType.DOCUMENT, NodeType.FILE)),
-    EdgeType.CONTRADICTS:   ((NodeType.DOCUMENT, NodeType.FILE),
-                             (NodeType.DOCUMENT, NodeType.FILE)),
-    EdgeType.EVOLVES_FROM:  ((NodeType.DOCUMENT, NodeType.FILE),
-                             (NodeType.DOCUMENT, NodeType.FILE)),
-}
-
-
-# ── Models ──────────────────────────────────────────────────────────────────
-class Visibility(str, Enum):
-    PRIVATE = "private"        # 소유자만
-    INTERNAL = "internal"      # 같은 조직
-    SHARED  = "shared"         # 명시 공유
-    PUBLIC  = "public"         # 누구나
-
-
-def _ulid() -> str:
-    """간이 ULID (timestamp + uuid4 base32). 외부 의존성 없이."""
-    ts = int(time.time() * 1000)
-    rand = uuid.uuid4().int & ((1 << 80) - 1)
-    encoded = (ts << 80) | rand
-    chars = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"   # Crockford
-    out: List[str] = []
-    for _ in range(26):
-        encoded, r = divmod(encoded, 32)
-        out.append(chars[r])
-    return "".join(reversed(out))
-
-
-def _now_iso() -> str:
-    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
-
-
-def encode_embedding(vec: Sequence[float]) -> Optional[bytes]:
-    """list[float] → SQLite BLOB. ``None`` 입력은 None 반환."""
-    if vec is None:
-        return None
-    if len(vec) != EMBED_DIM:
-        raise ValueError(
-            f"embedding dim mismatch: got {len(vec)}, expected {EMBED_DIM} "
-            f"(set LATTICEAI_EMBED_DIM to override)"
-        )
-    return struct.pack(f"<{EMBED_DIM}f", *vec)
-
-
-def decode_embedding(blob: Optional[bytes]) -> Optional[List[float]]:
-    if not blob:
-        return None
-    return list(struct.unpack(f"<{EMBED_DIM}f", blob))
-
-
-def cosine(a: Sequence[float], b: Sequence[float]) -> float:
-    """단순 코사인 유사도. numpy 없이."""
-    if not a or not b:
-        return 0.0
-    s = sum(x * y for x, y in zip(a, b))
-    na = sum(x * x for x in a) ** 0.5
-    nb = sum(y * y for y in b) ** 0.5
-    return s / (na * nb) if na and nb else 0.0
-
-
-@dataclass
-class Node:
-    """PPT 슬라이드 20 의 노드 정의."""
-    type: NodeType
-    label: str
-    id: str = field(default_factory=lambda: f"node:{_ulid()}")
-    attrs: Dict[str, Any] = field(default_factory=dict)
-    embedding: Optional[List[float]] = None
-    owner_id: Optional[str] = None
-    visibility: Visibility = Visibility.PRIVATE
-    created_at: str = field(default_factory=_now_iso)
-    updated_at: str = field(default_factory=_now_iso)
-    style: Optional[str] = None
-    tone: Optional[str] = None
-    importance_score: float = 0.0
-    last_used: Optional[str] = None
-
-    def validate(self) -> None:
-        if not isinstance(self.type, NodeType):
-            raise TypeError(f"Node.type must be NodeType, got {type(self.type)!r}")
-        if not self.label or not self.label.strip():
-            raise ValueError("Node.label is required and non-empty")
-        if len(self.label) > 240:
-            raise ValueError("Node.label max length is 240 chars")
-        if not isinstance(self.attrs, dict):
-            raise TypeError("Node.attrs must be a dict")
-        if not isinstance(self.visibility, Visibility):
-            raise TypeError("Node.visibility must be Visibility enum")
-        if self.embedding is not None and len(self.embedding) != EMBED_DIM:
-            raise ValueError(f"Node.embedding dim must be {EMBED_DIM}")
-
-    def to_json(self) -> Dict[str, Any]:
-        d = asdict(self)
-        d["type"] = self.type.value
-        d["visibility"] = self.visibility.value
-        # embedding 은 JSON 직렬화시 length 만 노출 (가독성)
-        if self.embedding is not None:
-            d["embedding"] = f"[…{len(self.embedding)} dims]"
-        return d
-
-
-@dataclass
-class Edge:
-    """PPT 슬라이드 21 의 엣지 정의."""
-    source: str
-    target: str
-    type: EdgeType
-    id: str = field(default_factory=lambda: f"edge:{_ulid()}")
-    weight: float = 1.0           # 강도 0..1
-    confidence: float = 1.0       # 추출 신뢰도 0..1
-    evidence: List[str] = field(default_factory=list)   # 근거(노드/청크 ID)
-    created_by: str = "user"      # extractor 식별자
-    created_at: str = field(default_factory=_now_iso)
-
-    def validate(self) -> None:
-        if not isinstance(self.type, EdgeType):
-            raise TypeError("Edge.type must be EdgeType")
-        if not self.source or not self.target:
-            raise ValueError("Edge.source and Edge.target are required")
-        if self.source == self.target and self.type is not EdgeType.SIMILAR_TO:
-            # SIMILAR_TO 외에는 자기참조 금지
-            raise ValueError(f"self-loop not allowed for {self.type.value}")
-        if not (0.0 <= self.weight <= 1.0):
-            raise ValueError("Edge.weight must be in [0, 1]")
-        if not (0.0 <= self.confidence <= 1.0):
-            raise ValueError("Edge.confidence must be in [0, 1]")
-
-    def to_json(self) -> Dict[str, Any]:
-        d = asdict(self)
-        d["type"] = self.type.value
-        return d
-
-
-def validate_endpoints(edge_type: EdgeType, src_type: NodeType, tgt_type: NodeType) -> None:
-    """엣지가 허용된 source/target 타입을 잇고 있는지 검증."""
-    rule = EDGE_ENDPOINT_RULES.get(edge_type)
-    if rule is None:
-        return
-    src_allowed, tgt_allowed = rule
-    if src_allowed is not None and src_type not in src_allowed:
-        raise ValueError(
-            f"{edge_type.value}: source must be one of "
-            f"{[t.value for t in src_allowed]}, got {src_type.value}"
-        )
-    if tgt_allowed is not None and tgt_type not in tgt_allowed:
-        raise ValueError(
-            f"{edge_type.value}: target must be one of "
-            f"{[t.value for t in tgt_allowed]}, got {tgt_type.value}"
-        )
-
-
 # ── SQLite v2 store ─────────────────────────────────────────────────────────
 SCHEMA_SQL = """
 CREATE TABLE IF NOT EXISTS kg_meta (
@@ -381,7 +266,9 @@ CREATE TABLE IF NOT EXISTS kg_meta (
 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,
@@ -399,31 +286,54 @@ CREATE TABLE IF NOT EXISTS edges_v2 (
   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,
-  UNIQUE(source, target, type),
+  -- Edge identity follows the *raw* legacy type, not the normalized type:
+  -- two distinct legacy types between the same pair (e.g. "mentions" and
+  -- "관련됨") must stay distinct edges even though both normalize to MENTIONS.
+  UNIQUE(source, target, legacy_type),
   FOREIGN KEY(source) REFERENCES nodes_v2(id) ON DELETE CASCADE,
   FOREIGN KEY(target) REFERENCES nodes_v2(id) ON DELETE CASCADE
 );
 
 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 스토어. sqlite-vec 가 있으면 벡터 인덱스도 활용,
-    없으면 Python cosine 으로 폴백."""
+    """가벼운 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
-        self._has_vec: Optional[bool] = None
 
     @contextmanager
     def _conn(self):
@@ -439,11 +349,11 @@ class KGStoreV2:
     # 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", "weight", "confidence",
-                     "evidence", "created_by", "created_at"},
-        "nodes_v2": {"id", "type", "label", "attrs", "embedding", "owner_id",
-                     "visibility", "created_at", "updated_at", "style", "tone",
-                     "importance_score", "last_used"},
+        "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", "visibility", "created_at",
+                     "updated_at", "style", "tone", "importance_score", "last_used"},
     }
 
     def _drop_stale_empty_v2_tables(self, conn: sqlite3.Connection) -> None:
@@ -476,161 +386,31 @@ class KGStoreV2:
                     table, sorted(missing), count,
                 )
 
-    def init_schema(self) -> None:
-        with self._conn() as conn:
-            self._drop_stale_empty_v2_tables(conn)
-            conn.executescript(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)),
-            )
-
-    # ── Upsert ───────────────────────────────────────────────
-    def upsert_node(self, node: Node) -> str:
-        node.validate()
-        node.updated_at = _now_iso()
-        with self._conn() as conn:
-            conn.execute(
-                """
-                INSERT INTO nodes_v2(id, type, label, attrs, embedding,
-                                     owner_id, visibility, created_at, updated_at,
-                                     style, tone, importance_score, last_used)
-                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-                ON CONFLICT(id) DO UPDATE SET
-                  type=excluded.type,
-                  label=excluded.label,
-                  attrs=excluded.attrs,
-                  embedding=COALESCE(excluded.embedding, nodes_v2.embedding),
-                  owner_id=excluded.owner_id,
-                  visibility=excluded.visibility,
-                  updated_at=excluded.updated_at,
-                  style=COALESCE(excluded.style, nodes_v2.style),
-                  tone=COALESCE(excluded.tone, nodes_v2.tone),
-                  importance_score=MAX(excluded.importance_score, nodes_v2.importance_score),
-                  last_used=COALESCE(excluded.last_used, nodes_v2.last_used)
-                """,
-                (
-                    node.id, node.type.value, node.label,
-                    json.dumps(node.attrs, ensure_ascii=False),
-                    encode_embedding(node.embedding),
-                    node.owner_id, node.visibility.value,
-                    node.created_at, node.updated_at,
-                    node.style, node.tone,
-                    float(node.importance_score), node.last_used,
-                ),
-            )
-        return node.id
-
-    def upsert_edge(self, edge: Edge, *, check_endpoints: bool = True) -> str:
-        edge.validate()
-        if check_endpoints:
-            src = self.get_node(edge.source)
-            tgt = self.get_node(edge.target)
-            if src is None or tgt is None:
-                raise ValueError("Edge endpoints must exist as nodes")
-            validate_endpoints(edge.type, src.type, tgt.type)
-        with self._conn() as conn:
-            conn.execute(
-                """
-                INSERT INTO edges_v2(id, source, target, type, weight,
-                                     confidence, evidence, created_by, created_at)
-                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-                ON CONFLICT(source, target, type) DO UPDATE SET
-                  weight=excluded.weight,
-                  confidence=excluded.confidence,
-                  evidence=excluded.evidence,
-                  created_by=excluded.created_by
-                """,
-                (
-                    edge.id, edge.source, edge.target, edge.type.value,
-                    float(edge.weight), float(edge.confidence),
-                    json.dumps(edge.evidence, ensure_ascii=False),
-                    edge.created_by, edge.created_at,
-                ),
-            )
-        return edge.id
-
-    # ── Read ─────────────────────────────────────────────────
-    def get_node(self, node_id: str) -> Optional[Node]:
-        with self._conn() as conn:
-            row = conn.execute(
-                "SELECT * FROM nodes_v2 WHERE id = ?", (node_id,)
-            ).fetchone()
-        return _row_to_node(row) if row else None
-
-    def list_nodes(self, *, type: Optional[NodeType] = None,
-                   owner_id: Optional[str] = None,
-                   limit: int = 100) -> List[Node]:
-        sql = "SELECT * FROM nodes_v2 WHERE 1=1"
-        args: List[Any] = []
-        if type is not None:
-            sql += " AND type = ?"
-            args.append(type.value)
-        if owner_id is not None:
-            sql += " AND owner_id = ?"
-            args.append(owner_id)
-        sql += " ORDER BY updated_at DESC LIMIT ?"
-        args.append(int(limit))
-        with self._conn() as conn:
-            rows = conn.execute(sql, args).fetchall()
-        return [_row_to_node(r) for r in rows]
-
-    def neighbors(self, node_id: str, *,
-                  edge_type: Optional[EdgeType] = None,
-                  direction: str = "both",
-                  limit: int = 50) -> List[Tuple[Edge, Node]]:
-        """node_id 에 인접한 (edge, other_node) 페어를 반환."""
-        if direction not in ("out", "in", "both"):
-            raise ValueError("direction must be 'out' | 'in' | 'both'")
-        clauses, args = [], []
-        if direction in ("out", "both"):
-            clauses.append("source = ?"); args.append(node_id)
-        if direction in ("in", "both"):
-            clauses.append("target = ?"); args.append(node_id)
-        sql = f"SELECT * FROM edges_v2 WHERE ({' OR '.join(clauses)})"
-        if edge_type:
-            sql += " AND type = ?"; args.append(edge_type.value)
-        sql += " ORDER BY weight DESC, confidence DESC LIMIT ?"
-        args.append(int(limit))
-        with self._conn() as conn:
-            edges = [_row_to_edge(r) for r in conn.execute(sql, args).fetchall()]
-            out: List[Tuple[Edge, Node]] = []
-            for e in edges:
-                other_id = e.target if e.source == node_id else e.source
-                row = conn.execute(
-                    "SELECT * FROM nodes_v2 WHERE id = ?", (other_id,)
-                ).fetchone()
-                if row:
-                    out.append((e, _row_to_node(row)))
-        return out
-
-    def search_similar(self, vec: Sequence[float], *,
-                       top_k: int = 8,
-                       type: Optional[NodeType] = None,
-                       owner_id: Optional[str] = None) -> List[Tuple[Node, float]]:
-        """코사인 기반 semantic search. sqlite-vec 가 없을 때의 폴백 구현."""
-        if len(vec) != EMBED_DIM:
-            raise ValueError(f"query embedding dim must be {EMBED_DIM}")
-        sql = "SELECT * FROM nodes_v2 WHERE embedding IS NOT NULL"
-        args: List[Any] = []
-        if type is not None:
-            sql += " AND type = ?"; args.append(type.value)
-        if owner_id is not None:
-            sql += " AND owner_id = ?"; args.append(owner_id)
-        with self._conn() as conn:
-            rows = conn.execute(sql, args).fetchall()
-        scored = []
-        for r in rows:
-            emb = decode_embedding(r["embedding"])
-            if emb is None:
-                continue
-            scored.append((_row_to_node(r), cosine(vec, emb)))
-        scored.sort(key=lambda x: x[1], reverse=True)
-        return scored[:top_k]
+    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 _init_schema_on(self, conn: sqlite3.Connection) -> None:
+        self._drop_stale_empty_v2_tables(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]:
@@ -659,123 +439,12 @@ class KGStoreV2:
         }
 
 
-# ── Row → model helpers ────────────────────────────────────────────────────
-def _row_to_node(row: sqlite3.Row) -> Node:
-    keys = row.keys() if hasattr(row, "keys") else []
-    return Node(
-        id=row["id"],
-        type=NodeType(row["type"]),
-        label=row["label"],
-        attrs=json.loads(row["attrs"] or "{}"),
-        embedding=decode_embedding(row["embedding"]),
-        owner_id=row["owner_id"],
-        visibility=Visibility(row["visibility"]),
-        created_at=row["created_at"],
-        updated_at=row["updated_at"],
-        style=row["style"] if "style" in keys else None,
-        tone=row["tone"] if "tone" in keys else None,
-        importance_score=float(row["importance_score"]) if "importance_score" in keys else 0.0,
-        last_used=row["last_used"] if "last_used" in keys else None,
-    )
-
-
-def _row_to_edge(row: sqlite3.Row) -> Edge:
-    return Edge(
-        id=row["id"],
-        source=row["source"],
-        target=row["target"],
-        type=EdgeType(row["type"]),
-        weight=float(row["weight"]),
-        confidence=float(row["confidence"]),
-        evidence=json.loads(row["evidence"] or "[]"),
-        created_by=row["created_by"],
-        created_at=row["created_at"],
-    )
-
-
-# ── Migration: legacy (nodes/edges) → v2 (nodes_v2/edges_v2) ───────────────
-def migrate_legacy_to_v2(db_path: str, *, dry_run: bool = False) -> Dict[str, int]:
-    """기존 ``knowledge_graph.py`` 가 만든 ``nodes`` / ``edges`` 테이블을
-    ``nodes_v2`` / ``edges_v2`` 로 복사. ``dry_run`` 이면 카운트만 반환.
-    """
-    counters = {"nodes_seen": 0, "nodes_migrated": 0,
-                "edges_seen": 0, "edges_migrated": 0, "edges_skipped": 0}
-    store = KGStoreV2(db_path)
-    store.init_schema()
-    with sqlite3.connect(db_path) as conn:
-        conn.row_factory = sqlite3.Row
-
-        # nodes
-        try:
-            old_nodes = conn.execute(
-                "SELECT id, type, title, summary, metadata_json, created_at, updated_at FROM nodes"
-            ).fetchall()
-        except sqlite3.OperationalError:
-            old_nodes = []
-        for r in old_nodes:
-            counters["nodes_seen"] += 1
-            if dry_run:
-                continue
-            node = Node(
-                id=r["id"],
-                type=NodeType.from_legacy(r["type"]),
-                label=r["title"] or "(untitled)",
-                attrs=_safe_json(r["metadata_json"]),
-                created_at=r["created_at"] or _now_iso(),
-                updated_at=r["updated_at"] or _now_iso(),
-            )
-            try:
-                store.upsert_node(node)
-                counters["nodes_migrated"] += 1
-            except Exception as exc:
-                # 잘못된 legacy row 는 스킵
-                _log_skip("node", r["id"], exc)
-
-        # edges
-        try:
-            old_edges = conn.execute(
-                "SELECT id, from_node, to_node, type, weight, metadata_json, created_at FROM edges"
-            ).fetchall()
-        except sqlite3.OperationalError:
-            old_edges = []
-        for r in old_edges:
-            counters["edges_seen"] += 1
-            if dry_run:
-                continue
-            meta = _safe_json(r["metadata_json"])
-            edge = Edge(
-                id=r["id"],
-                source=r["from_node"],
-                target=r["to_node"],
-                type=EdgeType.from_legacy(r["type"]),
-                weight=float(r["weight"] or 1.0),
-                confidence=float(meta.get("confidence", 1.0)),
-                evidence=list(meta.get("evidence", []) or []),
-                created_by=str(meta.get("created_by", "legacy")),
-                created_at=r["created_at"] or _now_iso(),
-            )
-            try:
-                store.upsert_edge(edge, check_endpoints=False)
-                counters["edges_migrated"] += 1
-            except Exception as exc:
-                counters["edges_skipped"] += 1
-                _log_skip("edge", r["id"], exc)
-    return counters
-
-
-def _safe_json(raw: Optional[str]) -> Dict[str, Any]:
-    if not raw:
-        return {}
-    try:
-        v = json.loads(raw)
-        return v if isinstance(v, dict) else {"_raw": v}
-    except (ValueError, TypeError):
-        return {"_raw": raw}
-
-
-def _log_skip(kind: str, ident: str, exc: Exception) -> None:
-    # 의도적으로 print: 마이그레이션은 일회성이라 로깅 인프라 의존 안 함
-    print(f"[migrate] skip {kind} {ident}: {exc}")
+# 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 ────────────────────────────────────────────────────────────────────
@@ -788,10 +457,6 @@ def _cli() -> int:
     sub_init = sub.add_parser("init", help="initialize v2 schema in a DB")
     sub_init.add_argument("db", help="path to sqlite db")
 
-    sub_mig = sub.add_parser("migrate", help="migrate legacy nodes/edges → v2")
-    sub_mig.add_argument("db", help="path to sqlite db")
-    sub_mig.add_argument("--dry-run", action="store_true")
-
     sub_stats = sub.add_parser("stats", help="print store statistics")
     sub_stats.add_argument("db", help="path to sqlite db")
 
@@ -800,10 +465,6 @@ def _cli() -> int:
         KGStoreV2(args.db).init_schema()
         print(f"initialized v2 schema in {args.db}")
         return 0
-    if args.cmd == "migrate":
-        out = migrate_legacy_to_v2(args.db, dry_run=args.dry_run)
-        print(json.dumps(out, indent=2, ensure_ascii=False))
-        return 0
     if args.cmd == "stats":
         print(json.dumps(KGStoreV2(args.db).stats(), indent=2, ensure_ascii=False))
         return 0

package/knowledge_graph.py

@@ -23,14 +23,23 @@ from pathlib import Path
 from typing import Any, Dict, Iterable, List, Optional, Tuple
 
 try:
-    from kg_schema import KGStoreV2
+    from kg_schema import KGStoreV2, NodeType, EdgeType, _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]
+    _exec_script = None  # type: ignore[assignment]
 
 # Default read source for the graph queries: v2 reconstruction views.
 # Override with LATTICEAI_KG_READ_V2=0 to fall back to the legacy tables.
 _READ_FROM_V2_DEFAULT = os.getenv("LATTICEAI_KG_READ_V2", "1") != "0"
 
+# Bump when the v2 projection layout changes (columns, normalization rules).
+# On init, a stale projection is dropped and rebuilt from the authoritative
+# legacy tables — safe because nodes_v2/edges_v2 only ever hold a derived view.
+# v4: summary nullable + verbatim (byte-faithful) projection of legacy values.
+_PROJECTION_VERSION = 4
+
 _llm_router_ref = None
 
 def set_llm_router(router_instance):
@@ -916,133 +925,192 @@ class KnowledgeGraphStore:
             )
         self._init_v2_schema()
 
-    # SQL views that reconstruct the *exact* legacy row shape on top of the v2
-    # tables, so the read methods can run unchanged against either source. The
-    # projection (see _v2_project_node/_edge) stashes summary + the original
-    # metadata_json + (via the type column) the legacy type string, so these
-    # views are byte-faithful to the legacy nodes/edges tables.
+    # SQL views that reconstruct the *exact* legacy row shape on top of the
+    # normalized v2 tables, so the read methods run unchanged against either
+    # source. The projection stores the raw legacy type string in ``legacy_type``
+    # and promotes summary + metadata to first-class columns (no more
+    # ``attrs._kg`` passthrough / ``evidence`` abuse), so these views are
+    # byte-faithful to the legacy nodes/edges tables.
     _V2_VIEWS_SQL = """
     CREATE VIEW IF NOT EXISTS kgv2_nodes AS
-      SELECT id, type,
+      SELECT id,
+             COALESCE(legacy_type, type) AS type,
              label AS title,
-             COALESCE(json_extract(attrs, '$._kg.summary'), '')   AS summary,
-             COALESCE(json_extract(attrs, '$._kg.metadata_json'), '{}') AS metadata_json,
+             summary,
+             attrs AS metadata_json,
              created_at, updated_at
       FROM nodes_v2;
     CREATE VIEW IF NOT EXISTS kgv2_edges AS
-      SELECT id, source AS from_node, target AS to_node, type, weight,
-             COALESCE(evidence, '{}') AS metadata_json, created_at
+      SELECT id, source AS from_node, target AS to_node,
+             COALESCE(legacy_type, type) AS type,
+             weight,
+             metadata AS metadata_json,
+             created_at
       FROM edges_v2;
     """
 
     def _init_v2_schema(self) -> None:
-        """Initialize the v2 tables + reconstruction views and backfill from legacy.
-
-        Completes the v2 migration: both write (dual-write projection in
-        _upsert_node/_upsert_edge) and read (read methods route to the kgv2_*
-        views when ``_READ_FROM_V2`` is on) flow through the v2 tables. Legacy
-        nodes/edges are retained as the durable source until the v2 path bakes in.
+        """Initialize the normalized v2 tables + reconstruction views, migrating
+        the projection layout when it is stale — **atomically**.
+
+        The entire DROP → CREATE → VIEWS → BACKFILL → version-stamp sequence runs
+        in a single transaction on one connection: on any failure it rolls back,
+        leaving the prior projection untouched and the version unchanged, so the
+        next startup simply retries. The migration only ever touches the v2
+        tables/views and the ``projection_version`` key — never the authoritative
+        legacy ``nodes``/``edges`` — so legacy data cannot be corrupted even if
+        the rebuild fails midway.
         """
-        if KGStoreV2 is None:
+        if KGStoreV2 is None or _exec_script is None:
             return
         try:
-            KGStoreV2(self.db_path).init_schema()
             with self._connect() as conn:
-                conn.executescript(self._V2_VIEWS_SQL)
-            self._backfill_v2_if_needed()
+                conn.execute("BEGIN")
+                stale = self._projection_version(conn) != _PROJECTION_VERSION
+                if stale:
+                    # The projection is non-authoritative; drop it so init_schema
+                    # recreates the tables with the current normalized columns.
+                    for stmt in (
+                        "DROP VIEW IF EXISTS kgv2_edges",
+                        "DROP VIEW IF EXISTS kgv2_nodes",
+                        "DROP TABLE IF EXISTS edges_v2",
+                        "DROP TABLE IF EXISTS nodes_v2",
+                    ):
+                        conn.execute(stmt)
+                # init_schema(conn=...) joins this transaction (no implicit commit)
+                KGStoreV2(self.db_path).init_schema(conn=conn)
+                _exec_script(conn, self._V2_VIEWS_SQL)
+                self._backfill_v2_on(conn, force=stale)
+                # version stamp commits together with the backfill — never stranded
+                conn.execute(
+                    "INSERT OR REPLACE INTO kg_meta(key, value) VALUES ('projection_version', ?)",
+                    (str(_PROJECTION_VERSION),),
+                )
         except Exception as e:
             logging.warning("knowledge_graph: v2 schema init/backfill skipped: %s", e)
 
-    def _backfill_v2_if_needed(self) -> None:
-        """Project legacy nodes/edges into the v2 tables when v2 is empty or stale.
+    def _projection_version(self, conn: sqlite3.Connection) -> int:
+        """Return the stored v2 projection layout version (0 if unknown).
+
+        A fresh DB (kg_meta absent) raises ``sqlite3.OperationalError`` here and
+        is correctly treated as version 0 → rebuild. Only sqlite errors are
+        swallowed so a real bug doesn't masquerade as a stale projection.
+        """
+        try:
+            row = conn.execute(
+                "SELECT value FROM kg_meta WHERE key='projection_version'"
+            ).fetchone()
+            return int(row["value"]) if row and row["value"] is not None else 0
+        except sqlite3.Error:
+            return 0
+
+    def _backfill_v2_if_needed(self, *, force: bool = False) -> None:
+        """Project legacy nodes/edges into v2 on a fresh transaction.
 
-        Non-destructive to legacy. Reprojects when the v2 rows predate the
-        ``_kg`` reconstruction blob (older enum-only backfill), so the views
-        stay faithful. Idempotent: no-ops once v2 carries the current projection.
+        Thin wrapper around :meth:`_backfill_v2_on` for callers (tests, ad-hoc
+        re-sync) that aren't already inside the migration transaction.
         """
         try:
             with self._connect() as conn:
-                v2_nodes = conn.execute("SELECT COUNT(*) FROM nodes_v2").fetchone()[0]
-                legacy_nodes = conn.execute("SELECT COUNT(*) FROM nodes").fetchone()[0]
-                if legacy_nodes == 0:
-                    return
-                if v2_nodes > 0:
-                    has_kg = conn.execute(
-                        "SELECT COUNT(*) FROM nodes_v2 WHERE json_extract(attrs,'$._kg') IS NOT NULL"
-                    ).fetchone()[0]
-                    if has_kg > 0:
-                        return  # current projection already present
-                # (re)project: clear v2 graph (not authoritative) and rebuild
-                conn.execute("DELETE FROM edges_v2")
-                conn.execute("DELETE FROM nodes_v2")
-                n = e = 0
-                for r in conn.execute(
-                    "SELECT id, type, title, summary, metadata_json, created_at, updated_at FROM nodes"
-                ).fetchall():
-                    self._v2_project_node(
-                        conn, r["id"], r["type"], r["title"] or "", r["summary"] or "",
-                        _safe_loads(r["metadata_json"]),
-                        created_at=r["created_at"], updated_at=r["updated_at"],
-                    )
-                    n += 1
-                for r in conn.execute(
-                    "SELECT id, from_node, to_node, type, weight, metadata_json, created_at FROM edges"
-                ).fetchall():
-                    self._v2_project_edge(
-                        conn, r["from_node"], r["to_node"], r["type"], float(r["weight"] or 1.0),
-                        _safe_loads(r["metadata_json"]), edge_id=r["id"], created_at=r["created_at"],
-                    )
-                    e += 1
-                logging.info("knowledge_graph: projected legacy → v2 (%d nodes, %d edges)", n, e)
+                self._backfill_v2_on(conn, force=force)
         except Exception as ex:
             logging.warning("knowledge_graph: v2 backfill skipped: %s", ex)
 
-    # ── v2 dual-write projection (legacy types + summary/metadata in attrs._kg) ──
+    def _backfill_v2_on(self, conn: sqlite3.Connection, *, force: bool = False) -> None:
+        """Project legacy nodes/edges into the normalized v2 tables on ``conn``.
+
+        Non-destructive to legacy. ``force`` rebuilds unconditionally (used after
+        a layout migration); otherwise it only projects when v2 is empty. The v2
+        graph is a derived projection, so clearing + rebuilding it is always safe.
+        Idempotent: no-ops once v2 carries the current projection. Copies the
+        legacy column values **verbatim** so the kgv2_* views are byte-faithful.
+        """
+        legacy_nodes = conn.execute("SELECT COUNT(*) FROM nodes").fetchone()[0]
+        if legacy_nodes == 0:
+            return
+        v2_nodes = conn.execute("SELECT COUNT(*) FROM nodes_v2").fetchone()[0]
+        if v2_nodes > 0 and not force:
+            return  # current projection already present
+        # (re)project: clear v2 graph (not authoritative) and rebuild
+        conn.execute("DELETE FROM edges_v2")
+        conn.execute("DELETE FROM nodes_v2")
+        n = e = 0
+        for r in conn.execute(
+            "SELECT id, type, title, summary, metadata_json, created_at, updated_at FROM nodes"
+        ).fetchall():
+            self._v2_project_node(
+                conn, r["id"], r["type"], r["title"], r["summary"], r["metadata_json"],
+                created_at=r["created_at"], updated_at=r["updated_at"],
+            )
+            n += 1
+        for r in conn.execute(
+            "SELECT id, from_node, to_node, type, weight, metadata_json, created_at FROM edges"
+        ).fetchall():
+            self._v2_project_edge(
+                conn, r["from_node"], r["to_node"], r["type"], float(r["weight"] or 1.0),
+                r["metadata_json"], edge_id=r["id"], created_at=r["created_at"],
+            )
+            e += 1
+        logging.info("knowledge_graph: projected legacy → v2 (%d nodes, %d edges)", n, e)
+
+    # ── v2 dual-write projection (normalized type, byte-faithful legacy values) ──
+    # The projection stores the legacy ``title``/``summary``/``metadata_json``
+    # values it is handed VERBATIM (no truncation or JSON re-encoding) so the
+    # kgv2_* views reproduce the legacy rows exactly. Callers (_upsert_* and the
+    # backfill) pass the already-canonical legacy column values.
     def _v2_project_node(
         self, conn: sqlite3.Connection, node_id: str, node_type: str, title: str,
-        summary: str, metadata: Optional[Dict[str, Any]],
+        summary: Optional[str], metadata_json: Optional[str],
         *, created_at: Optional[str] = None, updated_at: Optional[str] = None,
     ) -> None:
         if KGStoreV2 is None:
             return
         ts = updated_at or _now()
-        attrs = _json({"_kg": {"summary": (summary or "")[:1000], "metadata_json": _json(metadata)}})
+        norm_type = NodeType.from_legacy(node_type).value if NodeType is not None else node_type
         try:
             conn.execute(
                 """
-                INSERT INTO nodes_v2(id, type, label, attrs, owner_id, visibility,
-                                     created_at, updated_at, importance_score)
-                VALUES (?, ?, ?, ?, NULL, 'private', ?, ?, 0.0)
+                INSERT INTO nodes_v2(id, type, legacy_type, label, summary, attrs,
+                                     owner_id, visibility, created_at, updated_at,
+                                     importance_score)
+                VALUES (?, ?, ?, ?, ?, ?, NULL, 'private', ?, ?, 0.0)
                 ON CONFLICT(id) DO UPDATE SET
-                  type=excluded.type, label=excluded.label,
+                  type=excluded.type, legacy_type=excluded.legacy_type,
+                  label=excluded.label, summary=excluded.summary,
                   attrs=excluded.attrs, updated_at=excluded.updated_at
                 """,
-                (node_id, node_type, (title or "")[:240], attrs, created_at or ts, ts),
+                (node_id, norm_type, node_type, title, summary,
+                 metadata_json if metadata_json is not None else "{}",
+                 created_at or ts, ts),
             )
         except Exception as ex:
             logging.debug("knowledge_graph: v2 node projection skipped (%s): %s", node_id, ex)
 
     def _v2_project_edge(
         self, conn: sqlite3.Connection, from_node: str, to_node: str, edge_type: str,
-        weight: float, metadata: Optional[Dict[str, Any]],
+        weight: float, metadata_json: Optional[str],
         *, edge_id: Optional[str] = None, created_at: Optional[str] = None,
     ) -> None:
         if KGStoreV2 is None:
             return
-        meta = metadata or {}
         eid = edge_id or f"edge:{_sha256_text(f'{from_node}|{edge_type}|{to_node}')[:24]}"
+        norm_type = EdgeType.from_legacy(edge_type).value if EdgeType is not None else edge_type
+        meta_str = metadata_json if metadata_json is not None else "{}"
+        confidence = float(_safe_loads(meta_str).get("confidence", 1.0))
         try:
             conn.execute(
                 """
-                INSERT INTO edges_v2(id, source, target, type, weight, confidence,
-                                     evidence, created_by, created_at)
-                VALUES (?, ?, ?, ?, ?, ?, ?, 'legacy', ?)
-                ON CONFLICT(source, target, type) DO UPDATE SET
+                INSERT INTO edges_v2(id, source, target, type, legacy_type, weight,
+                                     confidence, evidence, metadata, created_by, created_at)
+                VALUES (?, ?, ?, ?, ?, ?, ?, '[]', ?, 'legacy', ?)
+                ON CONFLICT(source, target, legacy_type) DO UPDATE SET
+                  type=excluded.type,
                   weight=max(edges_v2.weight, excluded.weight),
-                  evidence=excluded.evidence
+                  confidence=excluded.confidence,
+                  metadata=excluded.metadata
                 """,
-                (eid, from_node, to_node, edge_type, float(weight),
-                 float(meta.get("confidence", 1.0)), _json(meta), created_at or _now()),
+                (eid, from_node, to_node, norm_type, edge_type, float(weight),
+                 confidence, meta_str, created_at or _now()),
             )
         except Exception as ex:
             logging.debug("knowledge_graph: v2 edge projection skipped (%s->%s): %s", from_node, to_node, ex)
@@ -1069,6 +1137,35 @@ class KnowledgeGraphStore:
         except Exception as ex:
             logging.debug("knowledge_graph: v2 edge delete mirror skipped: %s", ex)
 
+    def _v2_sync_report(self) -> Dict[str, Any]:
+        """Diagnose the dual-write invariant: legacy node/edge id sets must equal
+        the v2 projection's. Returns counts + any drift (ids missing from / extra
+        in v2). ``in_sync`` is True only when both id sets match exactly.
+
+        All legacy writes go through _upsert_node/_upsert_edge (which dual-write)
+        and every legacy delete is mirrored, so a non-empty drift signals a
+        bypassed write path — this is the runtime guard for that invariant.
+        """
+        if KGStoreV2 is None:
+            return {"available": False, "in_sync": True}
+        with self._connect() as conn:
+            legacy_nodes = {r[0] for r in conn.execute("SELECT id FROM nodes")}
+            v2_nodes = {r[0] for r in conn.execute("SELECT id FROM nodes_v2")}
+            legacy_edges = {r[0] for r in conn.execute("SELECT id FROM edges")}
+            v2_edges = {r[0] for r in conn.execute("SELECT id FROM edges_v2")}
+        return {
+            "available": True,
+            "in_sync": legacy_nodes == v2_nodes and legacy_edges == v2_edges,
+            "nodes_legacy": len(legacy_nodes),
+            "nodes_v2": len(v2_nodes),
+            "edges_legacy": len(legacy_edges),
+            "edges_v2": len(v2_edges),
+            "nodes_missing_from_v2": sorted(legacy_nodes - v2_nodes),
+            "nodes_extra_in_v2": sorted(v2_nodes - legacy_nodes),
+            "edges_missing_from_v2": sorted(legacy_edges - v2_edges),
+            "edges_extra_in_v2": sorted(v2_edges - legacy_edges),
+        }
+
     def _upsert_node(
         self,
         conn: sqlite3.Connection,
@@ -1080,6 +1177,11 @@ class KnowledgeGraphStore:
         raw: Optional[Dict[str, Any]] = None,
     ) -> str:
         now = _now()
+        # Canonical stored values, computed once and shared with the v2
+        # projection so legacy and v2 hold byte-identical strings.
+        title_s = title[:240]
+        summary_s = summary[:1000]
+        meta_json = _json(metadata)
         conn.execute(
             """
             INSERT INTO nodes(id, type, title, summary, metadata_json, raw_json, created_at, updated_at)
@@ -1091,10 +1193,10 @@ class KnowledgeGraphStore:
               raw_json=excluded.raw_json,
               updated_at=excluded.updated_at
             """,
-            (node_id, node_type, title[:240], summary[:1000], _json(metadata), _json(raw), now, now),
+            (node_id, node_type, title_s, summary_s, meta_json, _json(raw), now, now),
         )
         # dual-write: project into the v2 graph on the same transaction
-        self._v2_project_node(conn, node_id, node_type, title, summary, metadata,
+        self._v2_project_node(conn, node_id, node_type, title_s, summary_s, meta_json,
                               created_at=now, updated_at=now)
         return node_id
 
@@ -1109,6 +1211,7 @@ class KnowledgeGraphStore:
     ) -> str:
         edge_id = f"edge:{_sha256_text(f'{from_node}|{edge_type}|{to_node}')[:24]}"
         now = _now()
+        meta_json = _json(metadata)   # canonical string shared with the projection
         conn.execute(
             """
             INSERT INTO edges(id, from_node, to_node, type, weight, metadata_json, created_at)
@@ -1117,10 +1220,10 @@ class KnowledgeGraphStore:
               weight=max(edges.weight, excluded.weight),
               metadata_json=excluded.metadata_json
             """,
-            (edge_id, from_node, to_node, edge_type, float(weight), _json(metadata), now),
+            (edge_id, from_node, to_node, edge_type, float(weight), meta_json, now),
         )
         # dual-write: project into the v2 graph on the same transaction
-        self._v2_project_edge(conn, from_node, to_node, edge_type, float(weight), metadata,
+        self._v2_project_edge(conn, from_node, to_node, edge_type, float(weight), meta_json,
                               edge_id=edge_id, created_at=now)
         return edge_id
 
@@ -3072,7 +3175,7 @@ class KnowledgeGraphStore:
                 conn.execute(
                     """
                     DELETE FROM nodes_v2
-                    WHERE type='Topic'
+                    WHERE legacy_type='Topic'
                       AND id NOT IN (SELECT target FROM edges_v2)
                       AND id NOT IN (SELECT source FROM edges_v2)
                     """

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ltcai",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Lattice AI local MLX/cloud LLM workspace server",
   "homepage": "https://github.com/TaeSooPark-PTS/LatticeAI#readme",
   "repository": {

package/server.py

@@ -1121,7 +1121,7 @@ async def lifespan(app: FastAPI):
             except Exception:
                 pass
 
-app = FastAPI(title=f"Lattice AI Server ({APP_MODE})", version="0.5.0", lifespan=lifespan)
+app = FastAPI(title=f"Lattice AI Server ({APP_MODE})", version="0.5.1", lifespan=lifespan)
 
 CORS_ALLOWED_ORIGINS = [
     f"http://localhost:{DEFAULT_PORT}",
@@ -3466,7 +3466,7 @@ async def verify_cloud_models(force: bool = False, provider_filter: Optional[str
 
 @app.get("/health")
 async def health(request: Request):
-    base = {"status": "ok", "version": "0.5.0", "mode": APP_MODE}
+    base = {"status": "ok", "version": "0.5.1", "mode": APP_MODE}
     if not get_current_user(request) and REQUIRE_AUTH:
         return base
     engines = await asyncio.to_thread(engine_status)