ltcai 11.2.0 → 11.5.0

package/docs/v11.4.0_RUST_FOUNDATION_PLAN.md

@@ -0,0 +1,181 @@
+# v11.4.0 — Rust Foundation (설계 문서)
+
+> 상태: 계획 → 구현 → **출하됨(v11.4.0)**. Rust 전환의 단일 출처 설계
+> 문서. 설계·기획: 본 문서. 목표 아키텍처는 아래 다이어그램, 이번
+> 릴리스는 그 **Phase 1**이다.
+
+## 목표 아키텍처 (전환 완료 시점의 모습)
+
+```
+        Desktop(Tauri)    Browser Ext     VS Code Ext
+              └────────────────┼────────────────┘
+                        React / TypeScript
+                               │
+                       ┌───────▼───────┐
+                       │ Lattice Host  │  Rust
+                       │ (supervisor + │
+                       │  IPC/API 관문) │
+                       └───────┬───────┘
+          ┌────────────────────┼────────────────────┐
+     lattice-core         Agent Runtime         IPC / API
+     (Brain·Graph·        (Tools·Sandbox·       (gateway,
+      Memory·Storage)      Permission·Jobs)      native routes)
+          │                                          │
+      Ingestion ──── Retrieval(Vector·BM25·KG → Fusion → Rerank
+          │                     → Context Builder)
+          └──────────────┬──────────────┘
+                         ▼
+                Python AI Worker  ← 최종적으로 Python이 맡는 유일한 층
+                (MLX · Ollama · Cloud → LLM, chat/agent 추론)
+```
+
+## 왜 단계적인가 (정직성 원칙)
+
+현 Python 플랫폼은 44개 라우터 파일 · ~448 라우트 · 40,488문 100.00%
+커버리지 플로어 위에 있다. 이것을 한 릴리스에 재작성하는 것은 "전체
+시스템에 지장 없음"과 양립할 수 없다. 그래서 각 릴리스가 **실제로
+작동하고 증명된 Rust 조각**을 늘려가고, Python은 마지막에 AI Worker
+(모델 추론)로 수렴한다. 11.4.0은 그 뼈대를 세운다.
+
+## Phase 1 스코프 (11.4.0)
+
+`rust/` cargo workspace 신설 — 3개 크레이트, 전부 tauri 비의존(우분투
+CI에서 시스템 패키지 없이 테스트 가능):
+
+### 1. `lattice-core` — Brain 저장소 읽기 층 + 임베딩 산술
+
+- 데이터 디렉터리 해석: `LATTICEAI_DATA_DIR` → 기본 `~/.ltcai`,
+  DB는 `knowledge_graph.sqlite` (Python과 동일 파일).
+- 읽기 전용 SQLite 접속(rusqlite `bundled` + **fts5 필수**): WAL,
+  `busy_timeout` 명시(Python은 미설정 — Rust가 양보하는 쪽).
+- 스키마 리더: `kgv2_nodes`/`kgv2_edges` 뷰(어휘·그래프 lane),
+  `nodes`/`chunks`/`vector_embeddings`(벡터 lane),
+  `nodes_v2`(워크스페이스 스코핑) — **lane별 테이블 이원화는 Python
+  현행 그대로** 재현한다.
+- 임베딩 모듈 = `lattice_brain/embeddings.py`의 1:1 포트:
+  토크나이저(`[a-z0-9][a-z0-9_.:/+-]{1,}` + latin 3-gram(len≥5) +
+  한국어 2-gram(len≥3)), blake2b-8 해시 bag-of-features(하위 비트 부호),
+  L2 정규화, `<f32` LE 인코딩/디코딩(4B/dim, 헤더 없음), 유사도는
+  **순수 내적**(dim 불일치는 하드 에러). 기본 dim 384,
+  모델 id `lattice-local-hash-v1:{dim}`.
+
+### 2. `lattice-retrieval` — 네이티브 하이브리드 검색 (패리티 증명 동반)
+
+패리티 대상은 **graph-layer `KnowledgeGraphStore.hybrid_search`**
+(2채널 alpha 융합)와 그 구성 lane인 `search()`(키워드),
+`vector_search()`(벡터). 서비스 층 3채널 융합(`SearchService`)은
+traverse/relationship 의존이 커서 Phase 2로 명시 이월.
+
+기본 env 구성(brute 백엔드, RRF/그래프 확장/이미지 융합/CE rerank 꺼짐)
+에서 다음을 정확 재현:
+
+- **키워드 lane**: trigram FTS5 `MATCH '"…"'`(내부 `"` 이중화,
+  len<3 → 빈 결과) → LIKE 폴백(`%q%`, `updated_at DESC, id ASC`) →
+  topic-term 보충(`limit*3`) → **(hits, type_boost, updated_at) 재점수**
+  (hits = topic 후보 12개의 대소문자 무시 부분일치 수, type_boost
+  집합 고정) + **2-pass 안정 정렬(id ASC → score DESC)**. 점수는
+  호출측 1/rank.
+- **벡터 lane**: `embedding_model+dim` 필터, `indexed_at DESC` 후보
+  상한(기본 10000, `LATTICEAI_VECTOR_MAX_CANDIDATES`), 순차 f64 내적
+  (Python과 동일 누적 순서 → bit-exact), min_score 필터,
+  `(score, updated_at) DESC` 안정 정렬, recall/honesty 필드 동일.
+- **정책**: `classify_query`(ko/en 정규식, code→recency→person→fact
+  우선순위)는 **원 질의**에, rewrite(공백 축약 + filler 3규칙,
+  remainder≥4)는 검색 질의에. recency 클래스만 half-life 14일 감쇠
+  `0.5 + 0.5*recency`.
+- **융합**: lexical 1/rank, vector max-정규화, `alpha*vec+(1-α)*lex`,
+  `round(x,6)`(**banker's rounding** — CPython round와 동치 구현),
+  정렬 `(-score, node_id)`, identity rerank(`rerank_score=score`,
+  top_k 절단), 결과 JSON 필드·라벨(`fusion`, `sources`, `policy`,
+  `vector.*`) 전부 동형.
+- **스코핑**: `allowed_workspaces=None` ⇒ 스코핑 없음(로컬 신뢰 소유자
+  기본 경로) — fail-closed로 바꾸지 않는다. 빈 집합 ⇒ 아무것도 매치
+  안 됨. legacy-global(NULL)은 `include_legacy_global`로만 포함.
+
+**패리티 하네스(양방향 계약)**:
+- `scripts/generate_rust_parity_fixtures.py`(Python)가 실제 Python
+  쓰기 경로로 소형 스토어를 빚어 `rust/fixtures/parity_store.sqlite`
+  + 질의 세트(ko/en, 4 클래스, len<3, 무결과, 동점 tie) +
+  `rust/fixtures/golden/*.json`(Python 엔진의 hybrid/keyword/vector
+  출력)을 커밋 산출물로 생성.
+- `tests/unit/test_rust_parity_contract.py`: 커밋된 fixture DB에 대해
+  Python 엔진을 다시 돌려 golden과 일치함을 상시 단언 — Python 쪽
+  의미 변경이 골든을 조용히 무효화하지 못한다.
+- `lattice-retrieval`의 cargo 테스트: 같은 DB·같은 질의에 대해 Rust
+  출력 == 같은 golden. 점수는 기본 완전 일치(불가피한 tie 케이스만
+  1e-12, 사유 주석).
+
+### 3. `lattice-host` — 수퍼바이저 + IPC/API 게이트웨이
+
+- **수퍼바이저(lib + bin)**: Python 워커 스폰(명령 해석은 현행 Tauri
+  규칙 승계: `LATTICEAI_DESKTOP_BACKEND_CMD` → `ltcai` → python 후보 →
+  번들 트리; 현행 `sort()+dedup()`이 우선순위를 파괴하던 버그는 수정),
+  **`/health` HTTP 프로브**(현행 TCP 접속 프로브 대체), 크래시 시
+  지수 백오프 자동 재시작(상한·수동 정지 존중), 우아한 종료(SIGTERM →
+  유예 → SIGKILL), **포트 통일**: 기본 4825에서 시작해 빈 포트 탐색,
+  선택 포트를 워커 env(`LATTICEAI_PORT`)와 상위(Tauri `backend_origin`)
+  에 단일 출처로 공급. 로그는 기존 `~/.ltcai/desktop-sidecar.log` 계승.
+- **게이트웨이(axum, 127.0.0.1 전용)**: `/host/health`·`/host/status`
+  (수퍼바이저 상태), 네이티브 `/rust/search/{hybrid,keyword,vector}`
+  (lattice-retrieval 직결, 읽기 전용), 그 외 전 경로는 워커로 리버스
+  프록시(스트리밍/SSE 통과). Phase 1에서는 **옵트인 front-door**
+  (`lattice-host` 바이너리 실행 시) — 기존 진입 경로(ltcai CLI,
+  브라우저 직접 접속)는 그대로 둔다. 비-loopback 바인드 거부.
+
+### 4. Tauri 통합 (DMG가 새 기초 위에 올라탐)
+
+`src-tauri`는 `lattice-host`를 path 의존으로 소비: `main.rs`의 ad-hoc
+스폰/프로브/재시작 로직을 크레이트 호출로 대체(451줄 → 얇은 셸).
+Tauri 명령 5종(`backend_origin`/`backend_status`/`restart_backend`/
+`shutdown_backend`/`select_folder`)의 프론트 계약은 불변. 네트워크
+토폴로지도 불변(웹뷰는 여전히 `{origin}/app`) — 사용자 가시 변화 없이
+수퍼바이저 품질만 오른다(HTTP 헬스, 자동 재시작, 포트 충돌 처리).
+
+### 5. 게이트/CI/버전
+
+- ci.yml에 `rust` 잡 신설: ubuntu, stable 툴체인(핀), `cargo fmt
+  --check` + `clippy -D warnings` + `cargo test` — `rust/` workspace만
+  (tauri 시스템 의존 없음). src-tauri 빌드는 종전대로 릴리스 플로우
+  (macOS)에서.
+- `check_max_file_lines.mjs`에 `*.rs` 추가(상한 1,000, `src-tauri/gen`
+  ·`target` 제외). 모든 신규 Rust 파일 목표 ≤500줄.
+- `scripts/bump_version.py`와 `test_version_consistency.py`에
+  `rust/Cargo.toml`(workspace.package.version, 크레이트는
+  `version.workspace = true`) 편입 — 버전 단일 출처 유지.
+- Python 커버리지 플로어(문·분기 100%)와 프론트 100%는 그대로. Rust는
+  cargo 테스트 + 패리티 골든이 게이트.
+
+### 명시적 비-목표 (Phase 1에서 하지 않는 것)
+
+- 3채널 `SearchService.hybrid_search`/KG 읽기 API의 네이티브화(Phase 2),
+- Ingestion(Watch/Parse/Chunk/Dedup)·Jobs/Events/Scheduler(Phase 2~3),
+- Agent Runtime(Tools/Sandbox/Permission)의 Rust화(Phase 4),
+- 게이트웨이의 기본 front-door 승격(Phase 2에서 e2e로 검증 후),
+- HNSW/quantized 백엔드·CE rerank·이미지 late fusion 패리티(브루트
+  기본 경로만; 나머지는 요청 시 워커로 프록시되므로 기능 손실 없음).
+
+## 로드맵 (다이어그램 → 릴리스 매핑)
+
+| Phase | 릴리스 | 내용 | 상태 |
+|---|---|---|---|
+| 1 | **11.4.0** | workspace + core 읽기층 + retrieval 패리티 + host 수퍼바이저/게이트웨이(옵트인) + Tauri 통합 | **출하됨** |
+| 2 | **11.5.0** | 게이트웨이 front-door 기본화(데스크톱), KG 읽기·3채널 검색·history 네이티브, Ingestion Watch/Chunk/Dedup | **출하됨** |
+| 3 | **11.5.0** | Jobs/Events/Scheduler, Context Builder 네이티브 | **출하됨** |
+| 4 | **11.5.0** | Agent Runtime(Tools·Sandbox·Permission) Rust화 — 단, 루프 오케스트레이션 이식은 명시적 비-목표로 남음(v11.5.0 계획 §4c) | **출하됨(커널)** |
+
+Phase 2~4는 원래 11.5.x~12.0으로 나뉘어 있었으나 한 릴리스로 합쳐 출하했다
+([`v11.5.0_RUST_COMPLETE_PLAN.md`](v11.5.0_RUST_COMPLETE_PLAN.md)). 아래 §
+"명시적 비-목표"의 네 항목 중 마지막(HNSW/quantized·CE rerank·이미지 late
+fusion 패리티)만 여전히 미이식이며, 나머지는 11.5.0에서 닫혔다.
+
+## 릴리스 체크리스트 (11.4.0)
+
+1. W1(host) ∥ W2(core+retrieval+패리티) → W3(Tauri·CI·게이트·버전 배선).
+2. 전 게이트 로컬 그린(pytest 100% 플로어·프론트·lint 체인·cargo 3종)
+   + fresh venv 재검증.
+3. `bump_version.py 11.4.0`(rust workspace 포함) → OpenAPI 재생성 →
+   문서·releaseTheme("Rust Foundation") → claims(화면 무변경) →
+   `release:evidence` 재촬영(스크린샷 13종 + GIF) →
+   `release:artifacts`(DMG 포함) → validate/smoke.
+4. 브랜치 `release/v11.4.0` 커밋·푸시 → PR로 CI 그린 → 태그
+   `v11.4.0` → GitHub Release(정확한 파일명 5종).

package/docs/v11.5.0_RUST_COMPLETE_PLAN.md

@@ -0,0 +1,145 @@
+# v11.5.0 — Rust Complete (설계 문서)
+
+> 상태: 계획 → 구현 → **출하됨(v11.5.0)**. v11.4.0 Rust Foundation 계획의
+> Phase 2·3·4를 한 릴리스로 완결한다. 원칙 불변: **작동하고 증명된
+> 조각만 출하하고, Python 서버는 목표 다이어그램의 AI Worker로
+> 수렴하되 제거되지 않는다.** 모든 네이티브 경로는 패리티 골든 또는
+> 결정표 골든으로 잠근다.
+>
+> 통합 상태: **완료**. 네 크레이트의 라우터 팩토리는 게이트웨이의
+> 리버스 프록시 폴스루보다 앞에 마운트되어 있고(`rust/lattice-host/src/gateway/mounts.rs`),
+> 데스크톱은 기본으로 게이트웨이 토폴로지로 뜬다(`src-tauri/src/topology.rs`,
+> 안전 밸브 3종 유지). §2a의 CSRF origin 주입과 SSE `X-Accel-Buffering`
+> 보강도 배선 완료. §4c(에이전트 루프 오케스트레이션 이식)만 의도적으로
+> 남아 있으며, 그 이유는 아래 본문 그대로다.
+
+## Phase 2 — Front Door + 읽기/검색/히스토리 네이티브 + Ingestion 프리미티브
+
+### 2a. 게이트웨이 front-door 기본화 (데스크톱)
+- 정찰 확정 사실: 쿠키(host-only)·CSP(`connect-src 'self' http://127.0.0.1:*`)
+  ·리다이렉트(전부 상대)는 origin 전환에 안전. **유일한 차단기는 CSRF
+  origin 정책이 워커 자신의 포트로 빌드되는 것**(web_runtime.py:42-67,
+  csrf.py:154-164 — Host는 프록시가 hop-by-hop으로 제거).
+- 해소(Rust만으로): `worker_env`가
+  `LATTICEAI_CSRF_TRUSTED_ORIGINS=http://127.0.0.1:{gw},http://localhost:{gw}`
+  를 워커에 주입(config.py:170이 이미 파싱). 게이트웨이 SSE 프록시는
+  `X-Accel-Buffering: no`를 이벤트 스트림 응답에 보강.
+- Tauri는 기본적으로 **게이트웨이 origin으로 항해**(`backend_origin` =
+  게이트웨이). `LATTICEAI_DESKTOP_BACKEND_ORIGIN`/`LATTICEAI_DESKTOP_DIRECT=1`
+  이면 종전 직결 유지(안전 밸브). e2e: 게이트웨이 경유 스모크 추가.
+- 알려진 잔여(문서화): invite-link 절대 URL(Host 재작성), SSO redirect
+  기본값, permission UI 기본 URL — 데스크톱 front-door에서 워커 포트를
+  가리킴. 영향 좁음(관리자/SSO 경로), FEATURE_STATUS에 명시.
+
+### 2b. 3채널 검색·KG 읽기·히스토리 네이티브 (lattice-retrieval 확장)
+패리티 대상(정찰 §6·§7의 명세 그대로):
+- `graph_search`: direct 1/rank + relationship 0.75/rank + traverse
+  이웃 0.45/rank, score=max 병합, **안정 정렬(동점 삽입순, id 타이브레이크
+  없음 — Python 그대로)**, graph_context 축적.
+- `relationship_search`: 6-way LIKE, `ORDER BY weight DESC, created_at
+  DESC, id ASC`, 양 끝점 스코프 통과 시만 생존, 점수 없음.
+- `traverse`: 무방향 BFS, 라운드당 `limit*3` 엣지 캡(라운드 종속성
+  포함 재현), visited<limit 게이트, 노드 수화 `updated_at DESC, id ASC`.
+- 서비스층 `hybrid_search`(3채널): `weights` 명시=재작성/감쇠 없음,
+  None=policy 적용; 기여도 `w * max(score, 1/rank)` 합산; 채널 payload
+  에코; POST/GET 비대칭 재현.
+- 히스토리 읽기: `_scope_sql`(빈 allowed+no-legacy ⇒ 1=0), 그룹핑
+  (`legacy-previous-history` 버킷, updated_at DESC), get_conversation
+  (전체 로드 후 필터 — 동일 재현), search(부분일치, "마지막 30그룹"
+  슬라이스 그대로).
+- 골든: 기존 픽스처 스토어 확장(대화 행 추가) + 새 질의 세트,
+  Python 계약 테스트 확장. 게이트웨이 라우트:
+  `/rust/search/service-hybrid`, `/rust/graph/{search,relationships,traverse}`,
+  `/rust/history`, `/rust/history/{conversations,search}` (라우터 팩토리로
+  노출, X5가 마운트).
+
+### 2c. lattice-ingest — Watch · Parse · Chunk · Dedup (단일 작성자 원칙)
+- **typed chunking 1:1 포트**(_kg_common/text.py 명세 전부: plain 1200/160,
+  markdown 섹션 스택+200자 전방 병합, code 세그먼트 팩킹+1.5x 하드리밋,
+  prose 경계 백업 `max(start+1, end-overlap)`, overlap 클램프) +
+  chunk id `chunk:{sha256(f"{node}:{i}:{text}")[:24]}` (utf-8 replace).
+- 해시 규약: `_clean_text`+sha256(text_hash), content_hash 이원 규약
+  (파일=바이트 sha256, 텍스트=`type|uri|text`) 그대로.
+- 파일 워치: mtime 폴링 스냅샷(현행 folder_watch 의미론 — OS 워처
+  아님)을 Rust 타이머로; 변경 감지 시 **워커의 기존 인제스트 API로
+  위임**(`POST /knowledge-graph/ingest` type=note 또는 folder 재스캔
+  트리거) — 그래프 쓰기는 계속 Python 단일 작성자. Rust는 감지·파싱
+  (txt/md)·청킹·중복 판정까지 수행하고 결과를 검증 가능하게 반환.
+- 패리티: 청킹 골든(Python 생성기 — 4전략 × 경계 케이스 · 한/영 ·
+  PDF 페이지 오프셋 산술) 완전 일치.
+
+## Phase 3 — Jobs · Events · Scheduler + Context Builder
+
+### 3a. lattice-jobs — 스케줄러 (문서화된 갭의 해소)
+- FEATURE_STATUS:179-185 "아무것도 배경 임베드 큐를 몰지 않는다"를
+  닫는다: Rust 타이머(기본 60s, env 조절)가 워커의 **신규 additive
+  엔드포인트** `POST /api/index/drain`(이번 릴리스에 Python에 추가,
+  `IngestionPipeline.drain_vector_queue` 호출, require_user+게이트,
+  100% 커버)을 호출. 미완 ingestion job resume도 동일 타이머가
+  `GET /api/ingestion/jobs` → 조건부 `/resume`으로 재개(기본 꺼짐,
+  `LATTICEAI_JOBS_AUTORESUME=1` 옵트인).
+- `/host/jobs` 상태 라우트: 마지막 틱 결과·다음 예정·큐 카운트
+  (`vector_jobs` 읽기 전용 카운트는 lattice-core로 직접).
+- 이벤트: 틱 결과를 호스트 로그 + `/host/jobs`에 노출(간결·정직).
+
+### 3b. Context Builder 네이티브 (lattice-retrieval 내 모듈)
+- `lattice_brain/context.py`의 `ContextAssembler` 포트: approx_tokens
+  `(len+3)//4`, 고정 섹션 순서(memories→artifacts→knowledge→notes→recent),
+  greedy 예산 절단(`content[:remaining*4]`, 절단 후 재계측 동작 포함)
+  — 시임은 네이티브 검색/히스토리 리더로 주입. 골든: 동일 픽스처에서
+  Python 어셈블러 출력과 완전 일치. 게이트웨이 `/rust/context/assemble`.
+- 문서 생성용 context_builder(B)는 Phase 4 이후로 명시 이월(
+  search_for_document_generation 의존).
+
+## Phase 4 — Agent Runtime: Tools · Sandbox · Permission (안전 커널)
+
+**다이어그램의 라벨(Tools/Process/Sandbox/Permission)을 Rust가 소유**하고,
+LLM 추론·변이 도구 실행은 워커에 위임(그것이 AI Worker의 정의다).
+
+### 4a. 권한 커널 — 결정표 패리티
+- `normalize_mode`(별칭 표 포함), `effective_auto_approve`(모드×도구
+  집합×risk×change_class 전 분기), `is_circuit_breaker`(파괴 risk·루트/홈
+  경로·rm -rf 변형), `should_stage_proposal`, `plan_requires_approval`,
+  `block_reason_for_tool`(우선순위 체인), `classify_tool_call`
+  (MUTATING_TOOL_INVENTORY 27종) 전부 포트.
+- **결정표 골든**: Python 생성기가 (mode × tool × policy × args)
+  그리드 수백 케이스의 판정을 JSON으로 떠서 커밋; Rust와 Python 양쪽
+  계약 테스트가 같은 골든을 상시 단언(11.4.0 방식).
+
+### 4b. 도구 샌드박스 — 검증 패리티 + 네이티브 실행(읽기 전용)
+- `run_command` 검증기 포트: shlex 분해, 실행경로/allowlist/셸 연산자/
+  find·rg 플래그/절대경로·`..`·심링크 이스케이프 규칙, env 치환
+  (HOME=AGENT_ROOT, 고정 PATH). **검증 판정 골든**(명령 문자열 그리드)
+  완전 일치. 통과한 읽기 전용 명령(pwd/ls/find/cat/head/tail/wc/rg)은
+  Rust가 직접 실행(타임아웃 30s·출력 12,000자 캡 동일).
+- 파일 도구: `_resolve_path` 의미론(AGENT_ROOT 격리) + read/list 네이티브.
+- 게이트웨이 `/rust/agent/preflight`(계획/도구콜 배열 + mode → 판정
+  목록)와 `/rust/agent/exec`(커널 통과 읽기 전용 명령만 실행; 그 외
+  는 판정과 함께 거부) — 변이는 절대 실행하지 않는다.
+
+### 4c. 루프 위임 — `/rust/agent/run`
+- 워커 `/agent`(SSE)로 턴을 위임하되 호스트가 `permission_mode`를
+  스탬프하고, 반환 계획에 커널 preflight를 병기해 표면에 제공.
+  Python 루프 자체의 재작성은 **명시적 비-목표**(결정 커널이 잠긴
+  지금, 루프 이식은 후속 릴리스의 기계적 작업으로 남긴다 — 이유:
+  AgentDeps 12개 시임의 실배선 검증 없이 이식하면 증명 없는 재작성).
+
+## 게이트/검증/릴리스
+
+- 신규 크레이트 3종(lattice-ingest/jobs/agent) 워크스페이스 편입,
+  전 파일 ≤1,000줄(목표 ≤500), fmt/clippy/test CI rust 잡 그대로.
+- Python 추가분(drain 엔드포인트 등)은 문·분기 100% 유지.
+- 골든 4계열(검색·히스토리/청킹/컨텍스트/권한·명령 판정) 모두
+  양방향(계약 pytest + cargo 테스트).
+- 릴리스 절차는 11.4.0과 동일: bump 11.5.0 → 문서·테마("Rust
+  Complete") → evidence 재촬영(13종+GIF) → artifacts(DMG) →
+  main 커밋·푸시 → CI 그린.
+
+## 정직한 경계 (FEATURE_STATUS에 그대로 기재)
+
+- Python 서버는 계속 모든 제품 표면을 서빙한다 — front-door는
+  데스크톱 기본 + 옵트인 바이너리이며, 네이티브 라우트는 검증된
+  대체 경로다.
+- 문서 파서 매트릭스(pdf/docx/xlsx/pptx)·임베딩 생산·LLM 추론·변이
+  도구 실행·그래프 쓰기는 워커 소유(설계상 단일 작성자/AI Worker).
+- 에이전트 루프 오케스트레이션의 Rust 이식은 남는다(4c의 이유).

package/lattice_brain/__init__.py

@@ -26,7 +26,7 @@ from .storage import (
     storage_from_env,
 )
 
-__version__ = "11.2.0"
+__version__ = "11.5.0"
 
 __all__ = [
     "AgentRuntime",

package/lattice_brain/graph/_kg_common/__init__.py

@@ -0,0 +1,287 @@
+"""
+SQLite knowledge graph for Lattice AI workspace memory.
+
+The graph keeps raw event JSON, normalized node metadata, and edges in one
+portable database so it can later migrate to Neo4j/Postgres without changing
+the ingestion contract.
+"""
+
+# ruff: noqa: F401,F841
+
+import asyncio
+import hashlib
+import json
+import logging
+import math
+import os
+import platform
+import re
+import shutil
+import sqlite3
+import time
+import zipfile
+from collections import Counter
+from contextlib import contextmanager
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, Iterable, Iterator, List, Optional, Tuple
+
+try:
+    from ..schema import EdgeType, KGStoreV2, NodeType, _exec_script
+except Exception:  # pragma: no cover - v2 schema is optional at import time
+    KGStoreV2 = None  # type: ignore[assignment,misc]
+    NodeType = None  # type: ignore[assignment,misc]
+    EdgeType = None  # type: ignore[assignment,misc]
+    _exec_script = None  # type: ignore[assignment]
+
+from ...embeddings import LocalEmbeddingModel
+from ..json_utils import _json, _safe_loads
+from ..runtime import get_llm_router, set_llm_router
+
+# 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"
+
+# Static constants (projection/format versions, local-ingestion classification
+# tables, OS exclusion lists) live in ._kg_constants; re-exported here so every
+# existing ``from ._kg_common import <CONST>`` site is unaffected.
+from ...quiet import quiet
+from .._kg_constants import (  # noqa: E402
+    _KG_DB_FORMAT_KEY,
+    _KG_DB_FORMAT_VERSION,
+    _PROJECTION_VERSION,
+    _V2_WRITE_MASTER_KEY,
+    COMMON_EXCLUDED_DIRS,
+    COMMON_EXCLUDED_FILE_NAMES,
+    COMMON_EXCLUDED_FILE_SUFFIXES,
+    GRAPH_SCHEMA_VERSION,
+    LINUX_EXCLUDED_PREFIXES,
+    LOCAL_CODE_EXTENSIONS,
+    LOCAL_DOCUMENT_EXTENSIONS,
+    LOCAL_IMAGE_EXTENSIONS,
+    LOCAL_SIZE_LIMITS,
+    LOCAL_SLIDE_EXTENSIONS,
+    LOCAL_SPREADSHEET_EXTENSIONS,
+    LOCAL_SUPPORTED_EXTENSIONS,
+    LOCAL_TEXT_EXTENSIONS,
+    MACOS_EXCLUDED_PREFIXES,
+    SENSITIVE_PATH_KEYWORDS,
+    WINDOWS_EXCLUDED_NAMES,
+)
+
+# Pure fs/path/hash/classification helpers → ._kg_fsutil, re-exported so the
+# static __all__ below forwards them to the graph mixins. Listed explicitly
+# rather than star-imported: a star import here made every name in this
+# module unverifiable to both ruff and mypy.
+from .._kg_fsutil import (  # noqa: E402,F401
+    _current_os_type,
+    _drive_id_for_path,
+    _excluded_directory_reason,
+    _file_category,
+    _is_hidden_path,
+    _is_relative_to,
+    _node_type_for_category,
+    _now,
+    _parse_iso,
+    _parser_type_for_category,
+    _path_fingerprint,
+    _path_parts_lower,
+    _recency_score,
+    _root_warning,
+    _safe_iso_from_stat_mtime,
+    _sample_file,
+    _sensitive_file_reason,
+    _sha256_bytes,
+    _sha256_text,
+    _size_limit_for_category,
+    _slug,
+)
+
+# The logic this module used to hold inline lives in three cohesive submodules
+# (v11.3.0 decomposition). Every name is re-exported below, so the twelve
+# `from ._kg_common import *` consumers are unaffected — and `__all__` is still
+# the single written-down star-import contract.
+from .extraction import (  # noqa: E402
+    _CONCEPT_STOP,
+    _LLM_EXTRACT_CONCEPT_PROMPT,
+    _LLM_EXTRACT_TRIPLE_PROMPT,
+    ENABLE_LLM_EXTRACTION,
+    _extract_concepts,
+    _extract_concepts_rules,
+    _extract_triples,
+    _extract_triples_rules,
+    _llm_extract_concepts,
+    _llm_extract_triples,
+    _semantic_items,
+    _topic_candidates,
+)
+from .relations import (  # noqa: E402
+    _NOT_PERSON_WORDS,
+    COOCCURRENCE_CONCEPT_LIMIT,
+    COOCCURRENCE_EDGE_WEIGHT,
+    EDGE_VERB,
+    VERB_EDGE_WEIGHT,
+    _classify_node_type,
+    _infer_edge,
+    infer_edge_relation,
+)
+from .text import (  # noqa: E402
+    _CHUNK_STRATEGIES,
+    _CODE_BLANK_RUN_RE,
+    _CODE_BOUNDARY_LINE_RE,
+    _CODE_CHUNK_EXTENSIONS,
+    _MARKDOWN_CHUNK_EXTENSIONS,
+    _MARKDOWN_HEADING_RE,
+    _MARKDOWN_MIN_SECTION_CHARS,
+    _PROSE_CHUNK_EXTENSIONS,
+    _PROSE_MIN_SPAN_RATIO,
+    _PROSE_STRONG_BOUNDARY_RE,
+    _PROSE_WEAK_BOUNDARY_RE,
+    _chunks,
+    _clean_text,
+    _code_chunks,
+    _code_segment_spans,
+    _last_boundary,
+    _markdown_chunks,
+    _markdown_section_spans,
+    _merge_small_sections,
+    _plain_windows,
+    _prose_chunks,
+    chunk_strategy_for,
+    citation_locator,
+    page_for_offset,
+    pdf_page_offsets,
+    typed_chunk_meta_fields,
+    typed_chunks,
+)
+
+# Static export list. This used to be `[name for name in globals() if not
+# name.startswith("__")]`, which is invisible to a type checker: every
+# `from ._kg_common import *` consumer then had *no* resolvable names, and
+# mypy reported ~750 spurious `name-defined` errors across the graph
+# package. `tests/unit/test_kg_common_exports.py` asserts this list still
+# equals what the computed expression would produce, so it cannot drift.
+__all__ = [
+    "Any",
+    "COMMON_EXCLUDED_DIRS",
+    "COMMON_EXCLUDED_FILE_NAMES",
+    "COMMON_EXCLUDED_FILE_SUFFIXES",
+    "COOCCURRENCE_CONCEPT_LIMIT",
+    "COOCCURRENCE_EDGE_WEIGHT",
+    "Counter",
+    "Dict",
+    "EDGE_VERB",
+    "ENABLE_LLM_EXTRACTION",
+    "EdgeType",
+    "GRAPH_SCHEMA_VERSION",
+    "Iterable",
+    "Iterator",
+    "KGStoreV2",
+    "LINUX_EXCLUDED_PREFIXES",
+    "LOCAL_CODE_EXTENSIONS",
+    "LOCAL_DOCUMENT_EXTENSIONS",
+    "LOCAL_IMAGE_EXTENSIONS",
+    "LOCAL_SIZE_LIMITS",
+    "LOCAL_SLIDE_EXTENSIONS",
+    "LOCAL_SPREADSHEET_EXTENSIONS",
+    "LOCAL_SUPPORTED_EXTENSIONS",
+    "LOCAL_TEXT_EXTENSIONS",
+    "List",
+    "LocalEmbeddingModel",
+    "MACOS_EXCLUDED_PREFIXES",
+    "NodeType",
+    "Optional",
+    "Path",
+    "SENSITIVE_PATH_KEYWORDS",
+    "Tuple",
+    "VERB_EDGE_WEIGHT",
+    "WINDOWS_EXCLUDED_NAMES",
+    "_CHUNK_STRATEGIES",
+    "_CODE_BLANK_RUN_RE",
+    "_CODE_BOUNDARY_LINE_RE",
+    "_CODE_CHUNK_EXTENSIONS",
+    "_CONCEPT_STOP",
+    "_KG_DB_FORMAT_KEY",
+    "_KG_DB_FORMAT_VERSION",
+    "_LLM_EXTRACT_CONCEPT_PROMPT",
+    "_LLM_EXTRACT_TRIPLE_PROMPT",
+    "_MARKDOWN_CHUNK_EXTENSIONS",
+    "_MARKDOWN_HEADING_RE",
+    "_MARKDOWN_MIN_SECTION_CHARS",
+    "_NOT_PERSON_WORDS",
+    "_PROJECTION_VERSION",
+    "_PROSE_CHUNK_EXTENSIONS",
+    "_PROSE_MIN_SPAN_RATIO",
+    "_PROSE_STRONG_BOUNDARY_RE",
+    "_PROSE_WEAK_BOUNDARY_RE",
+    "_READ_FROM_V2_DEFAULT",
+    "_V2_WRITE_MASTER_KEY",
+    "_chunks",
+    "_classify_node_type",
+    "_clean_text",
+    "_code_chunks",
+    "_code_segment_spans",
+    "_current_os_type",
+    "_drive_id_for_path",
+    "_excluded_directory_reason",
+    "_exec_script",
+    "_extract_concepts",
+    "_extract_concepts_rules",
+    "_extract_triples",
+    "_extract_triples_rules",
+    "_file_category",
+    "_infer_edge",
+    "_is_hidden_path",
+    "_is_relative_to",
+    "_json",
+    "_last_boundary",
+    "_llm_extract_concepts",
+    "_llm_extract_triples",
+    "_markdown_chunks",
+    "_markdown_section_spans",
+    "_merge_small_sections",
+    "_node_type_for_category",
+    "_now",
+    "_parse_iso",
+    "_parser_type_for_category",
+    "_path_fingerprint",
+    "_path_parts_lower",
+    "_plain_windows",
+    "_prose_chunks",
+    "_recency_score",
+    "_root_warning",
+    "_safe_iso_from_stat_mtime",
+    "_safe_loads",
+    "_sample_file",
+    "_semantic_items",
+    "_sensitive_file_reason",
+    "_sha256_bytes",
+    "_sha256_text",
+    "_size_limit_for_category",
+    "_slug",
+    "_topic_candidates",
+    "asyncio",
+    "chunk_strategy_for",
+    "citation_locator",
+    "contextmanager",
+    "datetime",
+    "get_llm_router",
+    "hashlib",
+    "infer_edge_relation",
+    "json",
+    "logging",
+    "math",
+    "os",
+    "page_for_offset",
+    "pdf_page_offsets",
+    "platform",
+    "quiet",
+    "re",
+    "set_llm_router",
+    "shutil",
+    "sqlite3",
+    "time",
+    "typed_chunk_meta_fields",
+    "typed_chunks",
+    "zipfile",
+]