ltcai 11.5.2 → 11.6.0

package/lattice_brain/graph/schema.py

@@ -1,792 +0,0 @@
-"""
-Lattice AI — Knowledge Graph v2 schema (PPT spec aligned)
-=========================================================
-
-명세: ``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 lattice_brain.graph.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 logging
-import os
-import sqlite3
-from contextlib import contextmanager
-from enum import Enum
-from pathlib import Path
-from typing import Any, Dict, Optional
-
-from ..quiet import quiet
-from ..utils import now_iso as _stamp_now
-
-# ── Schema version ──────────────────────────────────────────────────────────
-KG_SCHEMA_V2_VERSION = 2
-EMBED_DIM = int(os.getenv("LATTICEAI_EMBED_DIM", "1024"))
-
-
-def set_embed_dim(dim: int) -> None:
-    """Optional way for upper layers to override without direct module import at top level in lattice_brain."""
-    global EMBED_DIM
-    EMBED_DIM = int(dim)  # lattice_brain isolation: no direct latticeai import; callers can pre-set env if using central Config
-
-
-# ── 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"  # 에이전트(역할/실행 주체)
-    # v11.1.0 Personal Ontology (Track 4) — the Self-Model subgraph. These are
-    # not "another kind of document": they are what the Brain has been told
-    # about *its owner*, so they are read, edited and deleted as a unit
-    # (``lattice_brain.self_model``). DECISION already exists above and is
-    # reused rather than duplicated — a decision is a decision whether it came
-    # from a meeting note or from "결정: 로컬 모델을 기본값으로 쓴다".
-    SELF = "SELF"  # 사용자 자신(Self-Model 루트)
-    PREFERENCE = "PREFERENCE"  # 선호 (좋아함/싫어함/선호 방식)
-    HABIT = "HABIT"  # 습관 (반복되는 행동)
-    RELATIONSHIP = "RELATIONSHIP"  # 관계 (동료/친구/멘토 등)
-    # v11.1.0 Multi-modal (Track 3) — a recording is its own noun. It used to
-    # enter through the text door as a DOCUMENT because "a transcript *is*
-    # text"; that is true of the transcript and false of the recording, which
-    # exists whether or not anyone could hear it. IMAGE has been first-class
-    # since 3.6.0 for the same reason, and AUDIO now sits beside it.
-    AUDIO = "AUDIO"  # 녹음 / 음성 메모
-    # v11.2.0 — a video is its own noun for the same reason a recording is:
-    # keyframes and subtitles are *derived* from it (IMAGE children, text
-    # chunks), and calling the thing they came from a DOCUMENT would make the
-    # source of a memory indistinguishable from one of its pieces.
-    VIDEO = "VIDEO"  # 영상 / 화면 녹화
-
-    @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:
-            quiet()
-        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:
-            quiet()
-        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,
-    # v11.1.0 Personal Ontology — the Self-Model vocabulary, including the
-    # Korean labels a person actually types.
-    "self": NodeType.SELF,
-    "selfmodel": NodeType.SELF,
-    "me": NodeType.SELF,
-    "나": NodeType.SELF,
-    "preference": NodeType.PREFERENCE,
-    "선호": NodeType.PREFERENCE,
-    "habit": NodeType.HABIT,
-    "습관": NodeType.HABIT,
-    "relationship": NodeType.RELATIONSHIP,
-    "관계": NodeType.RELATIONSHIP,
-    "결정": NodeType.DECISION,
-    # v11.1.0 Multi-modal — recordings as a first-class noun.
-    "audio": NodeType.AUDIO,
-    "오디오": NodeType.AUDIO,
-    # v11.2.0 — videos likewise.
-    "video": NodeType.VIDEO,
-    "영상": NodeType.VIDEO,
-    "동영상": NodeType.VIDEO,
-}
-
-_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,
-  -- Bitemporal validity (v11.1.0). NULL is the convention, not '':
-  --   valid_from IS NULL  → the row has been valid since created_at
-  --   valid_to   IS NULL  → the row is still valid now
-  -- An empty string would read as "valid since the beginning of time" in a
-  -- string comparison, which is why the columns are nullable with no default.
-  valid_from       TEXT,
-  valid_to         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,
-  -- Bitemporal validity + revision chain (v11.1.0), same NULL convention as
-  -- nodes_v2: NULL valid_from falls back to created_at, NULL valid_to means
-  -- "still holds". Relationships go stale exactly like facts do.
-  valid_from   TEXT,
-  valid_to     TEXT,
-  superseded_by TEXT,
-  -- 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);
-"""
-
-
-# ── Temporal read convention (v11.1.0) ──────────────────────────────────────
-# One predicate, shared by every ``as_of`` read so the fallback rule cannot
-# drift between call sites:
-#   * ``valid_from IS NULL``  → the row has been valid since ``created_at``
-#     (plan §10 mitigation: existing Brains keep working with no backfill)
-#   * ``valid_to IS NULL``    → the row is still valid
-# The window is half-open ``[valid_from, valid_to)``: the instant a fact is
-# superseded belongs to its successor, so an ``as_of`` at exactly that instant
-# returns exactly one of the two.
-TEMPORAL_PREDICATE_SQL = (
-    "COALESCE(valid_from, created_at) <= ? AND (valid_to IS NULL OR valid_to > ?)"
-)
-
-
-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 | Path"):
-        # Callers pass a Path (the store keeps db_path as a Path); sqlite3
-        # accepts either, so the annotation now matches what is actually
-        # handed in instead of forcing every call site to str() it.
-        self.db_path = str(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",
-            "valid_from",
-            "valid_to",
-            "superseded_by",
-        },
-        "nodes_v2": {
-            "id",
-            "type",
-            "legacy_type",
-            "label",
-            "summary",
-            "attrs",
-            "embedding",
-            "owner_id",
-            "workspace_id",
-            "visibility",
-            "superseded_by",
-            "valid_from",
-            "valid_to",
-            "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",
-            "valid_from": "TEXT",
-            "valid_to": "TEXT",
-        },
-        "edges_v2": {
-            "valid_from": "TEXT",
-            "valid_to": "TEXT",
-            "superseded_by": "TEXT",
-        },
-    }
-
-    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)),
-        )
-
-    # ── Temporal stamping (v11.1.0) ──────────────────────────
-    #
-    # These are *primitives*, not a policy: the only caller in the product is
-    # the review-approval path in :mod:`lattice_brain.synthesis`. Background
-    # jobs and agents never call them directly — they raise a proposal and the
-    # user approves it. See ``ARCHITECTURE.md`` → "Temporal knowledge".
-    def stamp_node_validity(
-        self,
-        node_id: str,
-        *,
-        valid_from: Optional[str] = None,
-        valid_to: Optional[str] = None,
-        superseded_by: Optional[str] = None,
-    ) -> bool:
-        """Stamp a node's validity window. ``True`` when a row was updated.
-
-        Only the arguments actually supplied are written; ``None`` leaves the
-        stored value alone (it never clears a column back to NULL, so a second
-        resolution cannot silently un-supersede an earlier one).
-        """
-        return self._stamp_row(
-            "nodes_v2",
-            node_id,
-            {
-                "valid_from": valid_from,
-                "valid_to": valid_to,
-                "superseded_by": superseded_by,
-            },
-        )
-
-    def touch_node(self, node_id: str, *, at: Optional[str] = None) -> bool:
-        """Record one access: bump ``importance_score`` and set ``last_used``.
-
-        Read-path bookkeeping for the importance/decay report. Returns whether
-        a row existed; callers treat a ``False``/failure as harmless.
-        """
-        with self._conn() as conn:
-            cursor = conn.execute(
-                "UPDATE nodes_v2 SET importance_score = importance_score + 1.0, "
-                "last_used = ? WHERE id = ?",
-                (at or _stamp_now(), str(node_id)),
-            )
-            return int(cursor.rowcount or 0) > 0
-
-    def _stamp_row(
-        self, table: str, row_id: str, updates: Dict[str, Optional[str]]
-    ) -> bool:
-        fields = {key: value for key, value in updates.items() if value is not None}
-        if not fields:
-            return False
-        assignments = ", ".join(f"{key}=?" for key in fields)
-        with self._conn() as conn:
-            cursor = conn.execute(
-                f"UPDATE {table} SET {assignments} WHERE id=?",
-                (*fields.values(), str(row_id)),
-            )
-            return int(cursor.rowcount or 0) > 0
-
-    # ── 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())