ltcai 3.5.0 → 4.0.0

package/docs/kg-schema.md

@@ -78,8 +78,66 @@ Edge {
 | `VERSION_OF`    | `FILE → FILE` | 버전 히스토리 |
 | `GRANTS_ACCESS` | `PERSON → FILE`·`CONVERSATION`·`PROJECT` | 접근 권한 부여 |
 
-**엔드포인트 룰은 코드에서 강제된다** (`validate_endpoints` in `kg_schema.py`).
-잘못된 페어(예: `FILE → FILE` 에 `REPLIES_TO`)는 `upsert_edge` 가 거부한다.
+**엔드포인트 룰은 권고 사항이다 (스키마 문서 기준).** 코드에는 엔드포인트 페어
+검증기가 존재하지 않는다 — `validate_endpoints` 는 구현된 적이 없으며, 쓰기
+경로는 타입 페어를 거부하지 않는다. v4 의 쓰기 정규화는 *타입 어휘* 를
+강제한다: `_upsert_edge` 가 모든 엣지 타입을 canonical `EdgeType` 값으로
+정규화하므로 자유 문자열 타입은 더 이상 생성되지 않는다.
+
+---
+
+## v3.6.0 — Knowledge Graph First 엔티티/관계
+
+v3.6.0 은 "모든 데이터 소스가 Knowledge Graph 로 수렴한다"는 원칙을 1급 스키마로
+승격한다. 아래 타입은 **추가형(additive)**이다 — 기존 enum/legacy 매핑을 깨지 않고
+`from_legacy` 가 무손실로 정규화하며, 알 수 없는 타입은 여전히 `CONCEPT`/`MENTIONS` 로
+폴백한다. 스키마는 **확장 가능**하게 유지한다: 새 도메인 엔티티는 enum 멤버 1개 +
+`_LEGACY_NODE_MAP`/`_LEGACY_EDGE_MAP` 별칭만 추가하면 된다.
+
+### 추가 노드 타입
+
+| 타입 | 의미 | 대표 `attrs` / 출처 |
+|------|------|--------------------|
+| `SOURCE` | 수집 출처(파일/URL/브라우저 탭/git 등)의 **출처 노드** | `source_type`, `source_uri`, `content_hash`, `captured_at` |
+| `REPOSITORY` | git 저장소 | `remote`, `branch`, `head` |
+| `MEETING` | 회의 / 미팅 | `started_at`, `attendees[]` |
+| `ORGANIZATION` | 조직 / 회사 / 팀 | `domain`, `members[]` |
+| `WORKFLOW` | 워크플로우 정의/실행 | `workflow_id`, `status` |
+| `AGENT` | 에이전트(역할/실행 주체) | `role`, `model_id` |
+
+### 추가 엣지 타입
+
+| 타입 | 허용 source → target | 의미 |
+|------|---------------------|------|
+| `INDEXED_FROM` | ANY → `SOURCE` | 이 노드가 **어떤 출처에서 색인**됐는가 (provenance) |
+| `MODIFIED_BY` | ANY → `PERSON` | 마지막 수정자 |
+| `BELONGS_TO_PROJECT` | ANY → `PROJECT` | 프로젝트 귀속 |
+| `PART_OF` | ANY → ANY | 구성요소 관계 |
+| `DISCUSSED_IN` | `CONCEPT`·`DECISION` → `MEETING`·`CHAT` | 어디에서 논의됨 |
+| `DECIDED_BY` | `DECISION` → `PERSON` | 결정 주체 |
+| `GENERATED_BY` | ANY → `AGENT`·`MODEL`·`WORKFLOW` | 생성 주체 |
+| `USED_BY_AGENT` | ANY → `AGENT` | 에이전트가 사용함 |
+
+### 통합 수집 형태 (Unified Ingestion)
+
+모든 출처는 동일한 형태로 그래프에 들어온다:
+
+```
+SOURCE ──INDEXED_FROM◄── Document/File ──CONTAINS──► Chunk[]
+   ▲                          │
+   │                          └──(언급/포함)──► Concept / Task / Decision …
+provenance(source_type, source_uri, content_hash, captured_at, modified_at,
+           owner, workspace_id, permissions, pipeline, embedded, linked)
+```
+
+- **콘텐츠 노드**(Document/File/web 노드)는 `content_hash` 로 멱등(idempotent) 처리된다 —
+  같은 콘텐츠를 다시 수집하면 새 노드를 만들지 않고 갱신/링크한다.
+- 모든 콘텐츠 노드는 `SOURCE` 노드로 `INDEXED_FROM` 엣지를 가져 **출처를 항상 설명 가능**하다.
+- provenance 는 노드 `metadata.provenance` 에 임베드되며, 동시에 감사 가능한
+  `ingestion_provenance` 테이블에 기록된다 (`KnowledgeGraphStore.get_provenance(node_id)`).
+
+구현: `latticeai/services/ingestion.py` (`IngestionPipeline`) 가 단일 진입점이며,
+파일/로컬폴더/URL/브라우저 탭/텍스트를 모두 이 형태로 정규화한다.
 
 ---
 
@@ -143,20 +201,12 @@ Edge {
 
 ### 실행
 
-```bash
-# 1) 현재 DB 의 어떤 row 가 어떻게 변환될지만 보기
-python3 kg_schema.py migrate ~/.ltcai/knowledge_graph.db --dry-run
-
-# 2) 실제 마이그레이션 (v2 테이블에 복사. 기존 테이블은 보존)
-python3 kg_schema.py migrate ~/.ltcai/knowledge_graph.db
-
-# 3) 결과 확인
-python3 kg_schema.py stats ~/.ltcai/knowledge_graph.db
-```
-
-마이그레이션은 **기존 `nodes` / `edges` 를 건드리지 않는다.** 신규 `nodes_v2` / `edges_v2`
-테이블에 복사할 뿐이다. 새 코드가 안정화되면 다음 메이저 릴리스에서 legacy 테이블을
-DROP 한다.
+마이그레이션은 별도 CLI 없이 **서버 기동 시 자동으로** 일어난다:
+`knowledge_graph.KnowledgeGraphStore` 가 열릴 때 v2 스키마를 생성/치유하고
+(`kg_schema.KGStoreV2.init_schema` — 추가 컬럼은 `ALTER` 로 in-place 치유,
+edges_v2 식별자 변경은 create→copy→swap 으로 재구축), legacy 데이터를
+v2 로 백필한다. 기존 `nodes` / `edges` 테이블은 건드리지 않는다 — v4 의
+write-mastering 전환(T3d) 전까지 legacy 가 쓰기 마스터다.
 
 ---
 
@@ -164,47 +214,46 @@ DROP 한다.
 
 - 차원: 환경 변수 `LATTICEAI_EMBED_DIM` (기본 `1024`)
 - 저장: SQLite `BLOB` 컬럼, `struct.pack('<{n}f', …)` 직렬화
-- 검색: `KGStoreV2.search_similar(vec, top_k=8)` — sqlite-vec 가 없는 환경에서도
-  순수 Python 코사인으로 동작. sqlite-vec 가 설치되면 인덱스 자동 활용 (추후).
-
-임베딩 모델은 LLM 라우터(`llm_router.py`) 가 결정한다 — 기본 `sentence-transformers/all-MiniLM-L12-v2`
-(384-d, dim 변경시 `LATTICEAI_EMBED_DIM` 도 함께 설정).
+- 검색: `knowledge_graph.KnowledgeGraphStore.vector_search` — 순수 Python
+  코사인 (sqlite-vec/ANN 인덱스는 아직 없음). 기본 임베더는 해시 기반
+  폴백(`grade='fallback'`)이며, 실제 임베딩 모델은 setup wizard 를 통해
+  사용자 동의 하에 프로비저닝한다.
+- 키워드 검색: v4 부터 FTS5 trigram 인덱스(`node_fts`) 가 LIKE 스캔을
+  대체한다 (한국어 부분 문자열 리콜 유지). FTS5/trigram 이 없는 SQLite
+  빌드에서는 LIKE 경로가 그대로 동작하며 `index_status().storage.fts_enabled`
+  로 정직하게 보고된다.
 
 ---
 
 ## 사용 (Python)
 
+`KGStoreV2` 는 **스키마/초기화/통계 전용**이다 — 과거 문서에 있던
+`Node`/`Edge` dataclass, `upsert_node`/`upsert_edge`/`neighbors`/
+`search_similar` native API 는 제거되었고 존재하지 않는다. 데이터
+read/write 는 `knowledge_graph.KnowledgeGraphStore` 가 담당한다:
+
 ```python
-from kg_schema import KGStoreV2, Node, Edge, NodeType, EdgeType, Visibility
-
-store = KGStoreV2("/Users/me/.ltcai/kg_v2.db")
-store.init_schema()
-
-# 노드 만들기
-file_node = Node(
-    type=NodeType.FILE,
-    label="LatticeAI_기획서.pdf",
-    attrs={"mime": "application/pdf", "pageCount": 24, "lang": "ko"},
-    owner_id="user_seoljun",
-    visibility=Visibility.PRIVATE,
-)
-store.upsert_node(file_node)
-
-# 관계 만들기
-store.upsert_edge(Edge(
-    source=file_node.id,
-    target=concept_node.id,
-    type=EdgeType.MENTIONS,
-    weight=0.82, confidence=0.91,
-    evidence=["chunk:01HX7K…#p3"],
-    created_by="extractor:llm-gemma-4-12b",
-))
-
-# 이웃 탐색
-for edge, other in store.neighbors(file_node.id, edge_type=EdgeType.MENTIONS):
-    print(f"-[{edge.type.value}]-> {other.label}")
-
-# 의미 검색
-for node, score in store.search_similar(query_embedding, top_k=8):
-    print(f"{score:+.3f}  {node.type.value:>12}  {node.label}")
+from kg_schema import KGStoreV2, NodeType, EdgeType
+from knowledge_graph import KnowledgeGraphStore
+
+store = KnowledgeGraphStore(db_path, blob_dir)
+
+# 쓰기: 모든 ingest 경로가 내부적으로 _upsert_node/_upsert_edge 를 통과하며,
+# 엣지 타입은 canonical EdgeType 으로 정규화된다 (자유 문자열 차단).
+store.ingest_message("user", "프로젝트 일정 공유", user_email="me@example.com")
+
+# 읽기: search (FTS5/LIKE), vector_search, graph, traverse
+matches = store.search("프로젝트")["matches"]
+
+# v2 통계 (정규화된 타입 분포)
+print(KGStoreV2(store.db_path).stats())
 ```
+
+### v4 컬럼 (T3b/T3c)
+
+- `nodes_v2.workspace_id` — `NULL` = legacy-global (스코프 도입 이전 데이터)
+- `nodes_v2.visibility` — 신규 스코프 쓰기는 `workspace`/`private`,
+  스코프 없는 쓰기는 `legacy` (기존 공유 데이터를 몰래 private 으로
+  만들지 않는다)
+- `nodes_v2.superseded_by` — 개정 체인 (`mark_superseded`)
+- `edge_occurrences` — 관계의 모든 관측 기록 (observed_at/weight/source)

package/docs/privacy.md

@@ -13,8 +13,10 @@
 | 사용자 계정 | `~/.ltcai/users.json` | 이름, scrypt 해시 비밀번호, 역할 |
 | 세션 토큰 | `~/.ltcai/sessions.json` | UUID 토큰, 만료시간 |
 | 채팅 히스토리 | `~/.ltcai/chat_history.json` | 사용자-AI 대화 내용 |
-| 지식 그래프 | `~/.ltcai/knowledge_graph.sqlite` | 채팅/문서 노드/엣지 |
-| 업로드 파일 | `~/.ltcai/knowledge_graph_blobs/` | 원본 PDF/DOCX 등 |
+| 지식 그래프 | `~/.ltcai/knowledge_graph.sqlite` | 채팅/문서/웹/탭 노드·엣지, 프로비넌스 |
+| 업로드/수집 파일 | `~/.ltcai/knowledge_graph_blobs/` | 원본 PDF/DOCX/웹 텍스트 등 |
+| 수집 출처 기록(프로비넌스) | `~/.ltcai/knowledge_graph.sqlite` (`ingestion_provenance`) | 각 노드의 출처/시각/처리 방식 — 외부 전송 없음 |
+| 그래프 내보내기/백업 | `~/.ltcai/workspace_exports/` | 사용자가 직접 만든 로컬 export/backup 파일 (클라우드 미사용) |
 | 지식 정원 | `~/.ltcai-brain/` | P-Reinforce 분류 저장 |
 | 설정 | `~/.ltcai/config.json` | 모델 설정, API 키 (keyring) |
 
@@ -36,6 +38,20 @@
 
 Apple Silicon MLX 로컬 모델 사용 시에는 프롬프트가 외부로 전송되지 않습니다.
 
+## 웹/브라우저 수집 (v3.6.0)
+
+- **URL 읽기**(`/api/browser/read-url`): 사용자가 명시적으로 요청한 URL을 **로컬
+  런타임이 직접** 가져와 텍스트만 추출해 그래프에 색인합니다. Lattice AI가 임의로
+  크롤링하지 않으며, 가져온 페이지는 외부로 다시 전송되지 않습니다.
+- **브라우저 탭 수집**(`/api/browser/ingest-current-tab`) 및 Manifest V3 확장:
+  확장 프로그램은 **오직 `127.0.0.1`(로컬)** 로만 전송합니다. 클라우드 엔드포인트가
+  존재하지 않습니다(`browser-extension/` 소스에서 단일 `fetch` 대상 확인 가능).
+
+## 그래프 내보내기/백업 (v3.6.0)
+
+지식 그래프 export/import 및 백업/복원은 **전적으로 로컬**에서 동작하며 클라우드
+서비스를 요구하지 않습니다. 내보낸 파일의 이동·공유는 사용자 책임입니다.
+
 ## API 키 보안
 
 - API 키는 OS keyring(macOS Keychain, Windows Credential Manager, Linux Secret Service)에 저장됩니다

package/docs/security-model.md

@@ -78,6 +78,23 @@ MAGIC_NUMBERS = {
 - 업로드 시 파일 첫 바이트와 확장자 매핑 검증
 - 불일치 시 400 에러
 
+## 수집 & 그래프 포터빌리티 보안 (v3.6.0)
+
+- **수집 라이프사이클**: 모든 수집은 `IngestionPipeline.ingest` → `dispatch_tool`
+  를 거쳐 `pre_tool`/`post_tool` 훅이 발화됩니다. `pre_tool`이 차단하면 수집은
+  정직하게 `status="blocked"`로 거부됩니다(권한 게이트·민감정보 가드 적용).
+- **웹 URL 읽기**(`/api/browser/read-url`): `http(s)` 스킴만 허용(파일/기타 스킴
+  거부), 12초 타임아웃, 4MB 응답 상한, HTML/text 컨텐츠 타입만 처리. 차단/로그인
+  필요 페이지는 5xx가 아닌 **422로 우아하게 실패**합니다. 로컬 런타임이 사용자가
+  명시한 URL만 가져옵니다(자동 크롤링 없음).
+- **브라우저 탭 수집**(`/api/browser/ingest-current-tab`): payload 정화(스크립트/
+  스타일 제거) + 페이로드 크기 상한(413). Manifest V3 확장은 **`127.0.0.1`로만**
+  전송하며 클라우드 엔드포인트가 없습니다.
+- **포터빌리티 권한**: 그래프 export/status 읽기는 로그인 사용자, **import /
+  backup / restore 는 admin 전용**(`require_admin`). 그래프는 머신-전역 자원입니다.
+- **복원 무결성**: 백업 아카이브는 `manifest.json`의 sha256과 대조 검증 후에만
+  복원되며, 불일치 시 거부됩니다.
+
 ## 에이전트 도구 샌드박스
 
 ### `run_command()` 위험 플래그 차단

package/kg_schema.py

@@ -99,6 +99,15 @@ class NodeType(str, Enum):
     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":
@@ -107,8 +116,14 @@ class NodeType(str, Enum):
         매핑이 없는(동적 이벤트 등) 타입은 ``CONCEPT`` 로 폴백하지만, 호출부는
         원본 문자열을 ``legacy_type`` 칼럼에 별도 보존하므로 정보 손실은 없다.
         """
-        m = (label or "").strip().lower()
-        return _LEGACY_NODE_MAP.get(m, cls.CONCEPT)
+        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):
@@ -143,6 +158,16 @@ class EdgeType(str, Enum):
     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":
@@ -151,8 +176,13 @@ class EdgeType(str, Enum):
         매핑이 없는 동적 타입은 ``MENTIONS`` 로 폴백하지만, 호출부는 원본 문자열을
         ``edges_v2.legacy_type`` 에 보존하므로 정보 손실은 없다.
         """
-        m = (label or "").strip().lower()
-        return _LEGACY_EDGE_MAP.get(m, cls.MENTIONS)
+        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 매핑 표.
@@ -199,6 +229,19 @@ _LEGACY_NODE_MAP: Dict[str, NodeType] = {
     "보고서":       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] = {
@@ -254,6 +297,20 @@ _LEGACY_EDGE_MAP: Dict[str, EdgeType] = {
     "영감받음":      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 ─────────────────────────────────────────────────────────
@@ -272,7 +329,13 @@ CREATE TABLE IF NOT EXISTS nodes_v2 (
   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,
@@ -293,14 +356,33 @@ CREATE TABLE IF NOT EXISTS edges_v2 (
   metadata     TEXT NOT NULL DEFAULT '{}',
   created_by   TEXT NOT NULL DEFAULT 'user',
   created_at   TEXT NOT NULL,
-  -- 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),
+  -- 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);
@@ -352,8 +434,16 @@ class KGStoreV2:
         "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"},
+                     "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:
@@ -374,6 +464,13 @@ class KGStoreV2:
                 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]
@@ -400,8 +497,40 @@ class KGStoreV2:
         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 (?, ?)",