ltcai 11.1.0 → 11.4.0

package/docs/v11.3.0_PLAN.md

@@ -0,0 +1,202 @@
+# v11.3.0 — Time Remembers (설계 문서)
+
+> 상태: 계획 → 구현 → **출하됨(v11.3.0)**. 이 문서가 이번 릴리스의 설계
+> 단일 출처다. 설계·기획: 본 문서. 구현: 트랙별 작업 노트 참조.
+
+두 트랙을 하나의 릴리스로 출하한다.
+
+- **트랙 A — No Big Files**: 1,000줄 이상인 1st-party 소스 파일 28개를
+  전부 응집 단위로 분해하고, 재발을 막는 라인 상한 게이트를 lint에 추가한다.
+  동작 변화 0, 화면 변화 0.
+- **트랙 B — 기억의 연대기 (Brain Chronicle)**: v11.1.0이 심어 둔
+  bitemporal 데이터(`valid_from`/`valid_to`/`superseded_by`,
+  `edge_occurrences.observed_at`, `store.as_of()`)를 처음으로 사용자 앞에
+  꺼내는 7번째 주 화면. 두뇌가 자란 과정을 날짜로 보고, 임의 시점으로
+  되감는다.
+
+---
+
+## 트랙 A — No Big Files
+
+### 왜
+
+`frontend/src/styles.css`는 10,956줄이다. 그 아래로도 1,000줄을 넘는
+파일이 27개 있다. 리뷰가 느려지고, 에이전트 컨텍스트가 낭비되고, 충돌이
+잦아진다. "누가 봐도 큰 파일"이 리포에 남지 않게 한다.
+
+### 규칙
+
+- **상한: 파일당 1,000줄** (git-추적 1st-party `*.py *.ts *.tsx *.js
+  *.mjs *.cjs *.css` 전부 — 테스트 포함).
+- **제외(생성물/벤더)**: `frontend/src/api/openapi.ts`, `static/app/**`,
+  `static/vendor/**`, `node_modules`, `src-tauri/gen/**`.
+- **게이트**: `scripts/check_max_file_lines.mjs`가 `npm run lint` 체인에
+  들어간다. 상한 초과 파일을 경로+줄수로 나열하며 실패한다. 제외 목록은
+  스크립트 안에 사유 주석과 함께 명시한다.
+
+### 분해 대상 (28)
+
+CSS/프론트: `styles.css`(10,956) `graph-home.css`(1,387)
+`i18n/brain.ts`(1,647) `i18n/workspace.ts`(1,522)
+`client.test.ts`(1,131) `useBrainChat.test.tsx`(1,037)
+`vscode-extension/extension.ts`(1,104)
+
+Python(lattice_brain): `ingestion.py`(1,525) `portability.py`(1,347)
+`graph/_kg_common.py`(1,331) `graph/retrieval_vector.py`(1,293)
+`multimodal.py`(1,258) `graph/discovery_index.py`(1,141)
+`graph/retrieval.py`(1,120) `graph/projection.py`(1,008)
+
+Python(latticeai): `core/agent.py`(1,465) `runtime/build_phases.py`(1,450)
+`integrations/telegram_bot.py`(1,390) `setup/wizard.py`(1,310)
+`services/model_runtime.py`(1,281) `core/embedding_providers.py`(1,196)
+`services/memory_service.py`(1,177) `services/brain_intelligence.py`(1,083)
+`core/file_generation.py`(1,047) `models/router.py`(1,007)
+
+테스트/인프라: `tests/unit/test_layout_rebuild_apis.py`(1,685)
+`tests/visual/v3.spec.js`(1,246) `tests/visual/mock_server.cjs`(1,226)
+
+### 분해 프로토콜 (v10.0.1 교훈의 성문화)
+
+**Python** — 모듈 → 동명 패키지:
+
+1. `foo.py` → `foo/` 디렉터리. 내부를 응집 단위 서브모듈로 나눈다
+   (각 ≤1,000줄, 목표 ≤700줄).
+2. `foo/__init__.py`가 **모든 공개 이름 + 테스트가 참조하는 모든 이름**을
+   재수출한다. 기존 `__all__` 유지. import 경로는 단 하나도 깨지지 않는다.
+3. **monkeypatch 함정**: 테스트가 `patch("pkg.foo.bar")`로 패치하는
+   심볼은, `bar`를 사용하는 코드와 같은 서브모듈에 두거나 테스트의 패치
+   대상을 실제 위치로 갱신한다. 패키지 `__init__`에 재수출된 이름을
+   패치해도 서브모듈 내부의 전역 참조는 바뀌지 않는다.
+4. **모듈 전역 상태**(싱글턴, 캐시, 레지스트리)는 정확히 한 서브모듈에만
+   존재한다. 순환은 의존 순서 정리로 풀고, 문자열 리터럴 지연 import로
+   우회하지 않는다.
+5. **AST 동등성 증명**: 분해 전(`git show HEAD:<path>`)과 후(서브모듈
+   합집합)의 top-level 함수/클래스 각각에 대해 `ast.dump` 비교. import
+   문과 위치 이동 외 차이 0을 확인하고 결과를 작업 노트에 남긴다.
+6. `pyproject.toml`의 mypy `files` 목록을 새 경로로 갱신한다(원 모듈이
+   채택돼 있던 경우 서브모듈 전부 채택).
+
+**CSS** — `styles.css`는 이미 104개 섹션 주석으로 구조화되어 있다.
+섹션 묶음별로 `frontend/src/styles/core/*.css`로 옮기고 `styles.css`
+상단에서 원래 순서 그대로 `@import`한다. Tailwind v4는 unlayered 규칙이
+layered 유틸을 항상 이기므로 캐스케이드는 순서 보존이 전부다.
+**증명: 분해 전후 `vite build` 산출 CSS 번들이 동일해야 한다**
+(해시 제외 byte-diff).
+
+**i18n** — `brain.ts`/`workspace.ts`를 도메인별 사전 파일로 나누고 기존
+파일이 병합해 `registerCopy` 한 번만 호출한다. ko/en 키 패리티 테스트와
+`check_i18n_namespace_coverage.mjs`가 그대로 통과해야 한다.
+`vitest.config.ts`의 커버리지 제외 패턴을 `frontend/src/i18n/**`로
+넓힌다(사전은 로직이 아니다 — 기존 사유 그대로).
+
+**검증 플로어(불변)**: Python 문·분기 100.00% (`fail_under = 100`),
+프론트 4지표 100%, mypy 0 에러, ruff 클린, `npm run lint` 전 서브게이트,
+전 테스트 그린. 분해는 이 플로어 위에서만 성립한다.
+
+---
+
+## 트랙 B — 기억의 연대기 (Brain Chronicle)
+
+### 왜 이것인가
+
+v11.1.0이 노드·엣지에 `valid_from`/`valid_to`/`superseded_by`를 심고
+`edge_occurrences(observed_at)`와 `store.as_of()`/`neighbors(as_of=)`까지
+구현했지만, **이 데이터를 노출하는 HTTP 엔드포인트도, 화면도 0개다.**
+"두뇌가 시간을 기억한다"는 이 제품의 약속이 아직 보이지 않는다.
+연대기는 그 약속을 첫 화면급 표면으로 만든다. 전부 읽기 전용이라
+기존 시스템에 지장이 없다.
+
+### 사용자에게 보이는 것
+
+새 주 화면 **연대기** (라우트 id `chronicle`, 해시 `#/chronicle`,
+everyday 내비 4번째 항목). 위에서 아래로:
+
+1. **성장 곡선 + 스크러버** — 누적 기억(자료·개념·연결·대화)의 SVG 영역
+   차트. 핸들을 잡고 끌면 아래 전체가 그 시점으로 따라온다.
+2. **활동 히트맵** — 주×요일 격자, 하루의 활동 밀도. 클릭하면 그 날로.
+3. **그날의 이야기** — 선택한 날짜에 두뇌에 들어온 것들을 평이한 한국어
+   그룹 카드로: 자료(제목·출처), 새로 생긴 개념, 나눈 대화(첫 줄 미리보기),
+   달라진 사실(superseded/모순 해소). 각 카드는 기존 화면(기억 검색,
+   그래프, 대화)으로 연결된다.
+4. **그때의 두뇌 (되감기)** — 스크러버가 과거에 있을 때: 그 시점의
+   노드·연결 수와 그때 중요했던 개념 목록. `as_of` 읽기의 첫 노출.
+
+빈 두뇌엔 정직한 빈 상태: "오늘부터 기록이 쌓입니다." 요약 생성이나
+모델 호출은 없다 — 전부 이미 저장된 사실의 재배열이다(정직성 원칙).
+
+### API 계약 (신규 라우터, 전부 read-only)
+
+`latticeai/api/chronicle.py` — router-factory 규약(전체 경로, prefix 없음),
+`require_user` + `gate_read`, 워크스페이스 스코프. 서비스는
+`latticeai/services/chronicle.py`의 `ChronicleService`(순수 SQLite 읽기,
+날짜 버킷은 `latticeai/core/timezones.py` 기준).
+
+```
+GET /api/chronicle/overview
+  → { first_activity_at, last_activity_at,
+      totals: { sources, entities, connections, conversations },
+      series: [ { date, sources, entities, connections, conversations } ] }
+
+GET /api/chronicle/day/{date}          # YYYY-MM-DD, LATTICE_TZ 기준
+  → { date, counts, groups: {
+        sources:       [ { id, title, source_type, captured_at, node_id } ],
+        entities:      [ { id, label, type, created_at } ],
+        conversations: [ { conversation_id, preview, messages, started_at } ],
+        changes:       [ { kind, label, at, node_id } ] } }
+
+GET /api/chronicle/as-of?ts=<ISO8601>
+  → { ts, stats: { entities, connections },
+      top_entities: [ { id, label, type, importance_score } ] }
+```
+
+데이터 원천: `ingestion_provenance(created_at, captured_at)`,
+`nodes_v2`/`edges_v2`(`created_at`, temporal 3열),
+`conversation_messages(timestamp)`, `edge_occurrences(observed_at)`.
+`as-of`는 `store.as_of()` 계열을 통해서만 읽는다(중복 구현 금지).
+등록은 `build_phases.py` platform_features 단계에 직접 include.
+스키마 변경 0, 쓰기 0.
+
+### 프론트 구조
+
+- `frontend/src/pages/Chronicle.tsx` + `frontend/src/features/chronicle/`
+  (GrowthScrubber / ActivityHeatmap / DayStory / RewindPanel — 각 ≤1,000줄).
+- `routes.ts`: `productShellRoutes` 7번째 항목, `directProductRoutes`,
+  `commandRoutes`(팔레트), 별칭 `timeline` → `chronicle`.
+- `App.tsx`: lazy import + everyday 내비(대화·자료·기억·연대기).
+- i18n: 신규 네임스페이스 `frontend/src/i18n/chronicle.ts`
+  (ko/en 패리티, 페이지 청크에서 등록). basic 모드 어휘: 개발 용어 금지.
+- `api/client.ts`에 typed 메서드 3개. OpenAPI 재생성으로 타입 공급.
+- 시각 회귀: `tests/visual/mock_server.cjs`에 chronicle 3 엔드포인트
+  픽스처(채워진 상태) 추가 — 릴리스 스크린샷이 빈 화면을 찍지 않게 한다.
+
+### 테스트
+
+- 백엔드: 서비스 단위(빈 두뇌·단일 일자·다일자·workspace 경계·tz 경계·
+  as-of 과거/미래/경계)와 라우터(인증·게이트·404·검증 실패)를 실제
+  tmp_path SQLite 스토어로. 문·분기 100%.
+- 프론트: 신규 파일 4지표 100%. routes/parseHash, 팔레트 노출,
+  스크러버 드래그 → as-of 반영, 빈 상태.
+
+### 릴리스 증거
+
+- 신규 스크린샷 `13-chronicle.png` 캡처 목록 추가, README 기능 표에
+  연대기 카드 추가.
+- 내비가 화면 전체에 4번째 everyday 항목을 추가하므로
+  `scripts/release_screen_claims.json`의 11.3.0 항목은 topbar가 보이는
+  화면들을 claim한다.
+
+---
+
+## 릴리스 체크리스트 (11.3.0)
+
+1. 트랙 A → 트랙 B 순서로 구현(연대기가 분해된 `build_phases` 위에 얹힘).
+2. 전 게이트 로컬 그린 → fresh venv 재검증(coverage-100 교훈).
+3. `bump_version.py 11.3.0` → OpenAPI 재생성 → 문서 갱신
+   (`check_current_release_docs.mjs`의 releaseTheme = "Time Remembers"
+   갱신 포함 — README/RELEASE.md/RELEASE_NOTES.md 제목과 일치 필수).
+4. `npm run release:evidence` (스크린샷 12+1, walkthrough GIF).
+5. `npm run release:artifacts` → whl · tar.gz · tgz · vsix ·
+   **DMG**(`Lattice AI_11.3.0_aarch64.dmg`) → `release:validate`
+   (`--require-vsix --require-tgz --require-dmg`) → `release:smoke`.
+6. main 커밋·푸시 → 태그 `v11.3.0` → GitHub Release(정확한 파일명,
+   와일드카드 금지) → main CI 4종(CI·Visual·Sidecar·Audit) 그린 확인.

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.1.0"
+__version__ = "11.4.0"
 
 __all__ = [
     "AgentRuntime",

package/lattice_brain/gates.py

@@ -0,0 +1,125 @@
+"""Opt-in gates that can still be answered at runtime (v11.2.0).
+
+Every opt-in feature in this product used to decide once, in a constructor:
+``self._on = os.getenv("LATTICEAI_…") in {"1", …}``. That is correct for a
+process that reads its environment at boot and never changes its mind, and it
+is a dead end for the settings screen that is coming — a UI toggle cannot move
+a boolean that was already copied into ``self``.
+
+:class:`FeatureGate` is the seam that keeps both true at once. It answers at
+*call* time in a fixed order:
+
+1. a **bound resolver** — a callable the app layer supplies (the future
+   settings surface, a per-workspace policy, a test double);
+2. an explicit **override** set through :meth:`FeatureGate.set`;
+3. the **environment variable**, parsed exactly the way the hand-written
+   ``os.getenv`` checks it replaces did;
+4. the declared **default**.
+
+An untouched gate therefore behaves identically to the frozen read it replaced
+— same env var, same truthy words, same default — while a bound resolver wins
+without a single change at any construction site. Brain Core owns this because
+Brain Core owns the gates that matter most (multi-modal routing, sharing), and
+it may not import ``latticeai``.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Callable, Dict, Optional
+
+#: The words this product has always accepted for "on" / "off".
+TRUTHY = frozenset({"1", "true", "yes", "on"})
+FALSY = frozenset({"0", "false", "no", "off"})
+
+
+class FeatureGate:
+    """One opt-in switch, resolved when it is asked rather than when it is built."""
+
+    __slots__ = ("env_var", "default", "name", "detail", "_override", "_resolver")
+
+    def __init__(
+        self,
+        env_var: str,
+        *,
+        default: bool = False,
+        name: str = "",
+        detail: str = "",
+    ) -> None:
+        self.env_var = env_var
+        self.default = bool(default)
+        self.name = name or env_var
+        #: Plain sentence for a surface that has to explain why a feature is off.
+        self.detail = detail
+        self._override: Optional[bool] = None
+        self._resolver: Optional[Callable[[], bool]] = None
+
+    # ── resolution ───────────────────────────────────────────────────────────
+    def __call__(self) -> bool:
+        return self.enabled()
+
+    def enabled(self) -> bool:
+        """The gate's answer *now* (resolver → override → env → default)."""
+        if self._resolver is not None:
+            return bool(self._resolver())
+        return self.local()
+
+    def local(self) -> bool:
+        """This gate's own answer, ignoring any bound resolver.
+
+        The lower three layers on their own (override → env → default). A
+        resolver that only has an opinion *sometimes* — a settings service that
+        speaks for the features a person actually touched, and stays quiet about
+        the rest — hands the question back here, so an operator's environment
+        variable keeps working for everything nobody has decided.
+        """
+        if self._override is not None:
+            return self._override
+        return self.from_env()
+
+    def from_env(self) -> bool:
+        """The environment's answer alone, ignoring resolver and override."""
+        raw = os.getenv(self.env_var, "").strip().lower()
+        if raw in TRUTHY:
+            return True
+        if raw in FALSY:
+            return False
+        return self.default
+
+    def source(self) -> str:
+        """Which of the four layers produced the current answer."""
+        if self._resolver is not None:
+            return "resolver"
+        if self._override is not None:
+            return "override"
+        if os.getenv(self.env_var, "").strip().lower() in (TRUTHY | FALSY):
+            return "env"
+        return "default"
+
+    # ── injection ────────────────────────────────────────────────────────────
+    def set(self, value: Optional[bool]) -> None:
+        """Explicit runtime override. ``None`` hands the answer back to the env."""
+        self._override = None if value is None else bool(value)
+
+    def bind(self, resolver: Optional[Callable[[], bool]]) -> None:
+        """Delegate the answer to a caller-supplied callable (``None`` unbinds)."""
+        self._resolver = resolver
+
+    def reset(self) -> None:
+        """Forget both injections — the gate is env-driven again."""
+        self._override = None
+        self._resolver = None
+
+    def describe(self) -> Dict[str, object]:
+        """Honest read for a status surface: state *and* where it came from."""
+        return {
+            "name": self.name,
+            "flag": self.env_var,
+            "enabled": self.enabled(),
+            "default": self.default,
+            "source": self.source(),
+            "detail": self.detail,
+        }
+
+
+__all__ = ["FALSY", "TRUTHY", "FeatureGate"]