ltcai 11.2.0 → 11.4.0

package/docs/v11.4.0_RUST_FOUNDATION_PLAN.md

@@ -0,0 +1,176 @@
+# 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.x | 게이트웨이 front-door 기본화, KG 읽기·3채널 검색·history 네이티브, Ingestion Watch/Chunk/Dedup |
+| 3 | 11.6.x | Jobs/Events/Pipeline/Scheduler, Context Builder 네이티브 |
+| 4 | 12.0 | Agent Runtime(Tools·Process·Sandbox·Permission) Rust화 — Python은 AI Worker로 수렴 |
+
+## 릴리스 체크리스트 (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/lattice_brain/__init__.py

@@ -26,7 +26,7 @@ from .storage import (
     storage_from_env,
 )
 
-__version__ = "11.2.0"
+__version__ = "11.4.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",
+]