ltcai 10.9.0 → 11.0.1

package/docs/v11.1.0_PRODUCT_INTELLIGENCE_PLAN.md

@@ -0,0 +1,313 @@
+# LatticeAI v11.1.0 — Full Feature Sprint Plan
+
+**목표 버전**: `11.1.0`  
+**포지셔닝**: Foundation Hardening (v9–v11.0) → **Product Intelligence Layer**  
+**원칙**: 보안/커버리지 게이트는 회귀만 유지. 새로운 기능 개발에 집중.  
+**범위**: 아래 5개 트랙을 **한 릴리즈에서 모두** 완료한다.  
+**작성일**: 2026-08-10  
+
+---
+
+## 0. 한 줄 요약
+
+> **벡터 검색을 스케일 가능하게 만들고 → Brain이 스스로 생각하고 모순을 감지하게 만들고 → 멀티모달을 1등 시민으로 올리고 → 개인 온톨로지 + 에이전트 워크스페이스를 붙이고 → 외부 지식 도구와 선택적 공유까지 연결한다.**
+
+이 순서는 **의존성**과 **제품 체감 가치**를 동시에 고려한 것이다.  
+앞 단계가 없으면 뒤 단계가 의미가 없거나 성능/품질이 붕괴한다.
+
+---
+
+## 1. 전체 의존성 & 실행 순서 (강제)
+
+```
+[1] High-Perf Vector + Incremental/Background Indexing
+        ↓ (스케일·속도 확보)
+[2] Proactive Synthesis + Contradiction + Temporal Reasoning
+        ↓ (Brain이 "살아있다"는 지능 레이어)
+[3] Multi-modal as First-Class Graph Citizen
+        ↓ (이미지/오디오가 진짜 기억이 됨)
+[4] Personal Ontology / Self-Model + Agent-Native Workspace OS
+        ↓ (개인화 + 장기 자율성)
+[5] Interop Bridges + Selective Encrypted Brain Network
+```
+
+**왜 이 순서인가**
+
+| 순서 | 이유 |
+|------|------|
+| 1 | 현재 brute-force 벡터 검색이 5k 노드에서 ~1.7초. 이 병목을 제거하지 않으면 2~5번 기능을 붙여도 체감이 안 난다. |
+| 2 | `proactive.py`가 이미 읽기 전용으로 존재. 벡터 품질이 올라가야 모순 감지·합성이 신뢰 가능해진다. |
+| 3 | 스키마(IMAGE 등)는 이미 있다. 하지만 retrieval/embedding 파이프라인이 텍스트 중심이라 멀티모달이 붙으면 검색 품질이 떨어질 수 있다 → 1번 이후. |
+| 4 | AgentRuntime + Change Governor가 이미 있다. 개인 온톨로지와 워크스페이스 OS는 2·3번이 만든 “풍부한 기억” 위에 올려야 의미 있다. |
+| 5 | 인제스트 게이트와 포트어빌리티가 안정된 뒤에야 외부 브릿지와 네트워크 공유가 안전하다. |
+
+**병렬 가능 구간**
+- 1번 진행 중에도 2번의 **스키마/데이터 모델 설계**와 4번의 **온톨로지 스키마 설계**는 병행 가능.
+- 3번의 비전 임베딩 프로바이더 실험은 1번과 거의 독립적으로 가능.
+- 5번의 Obsidian/Notion 파서 프로토타입은 인제스트 파이프라인만 안정되면 초반부터 가능.
+
+---
+
+## 2. 공통 가드레일 (모든 트랙에 적용)
+
+1. **SQLite는 여전히 Source of Truth**. 벡터 인덱스, 파생 그래프, 캐시는 모두 파생물. 깨져도 재구축 가능해야 한다.
+2. **Change Governor / Proposal-first** 유지. 에이전트가 Brain을 직접 쓰면 안 되고, 제안 → 리뷰 → 적용 경로를 탄다.
+3. **Local-first 기본값**. 클라우드 모델·네트워크·공유는 전부 opt-in.
+4. **정직성(Honest by design)**. 검색 품질, 벡터 freshness, 모순 존재 여부, 멀티모달 추출 품질을 사용자에게 숨기지 않는다.
+5. **문서 동기화**. 기능이 들어가면 `ARCHITECTURE.md`, `FEATURE_STATUS.md`, `RELEASE_NOTES`, `AGENTS.md`의 현재 릴리즈 마커를 같은 커밋에서 업데이트.
+6. **테스트 전략 변경**. 새 기능은 단위 테스트 + 통합 시나리오 테스트만 추가. 커버리지 %를 억지로 올리지 않는다. 기존 100% 게이트는 회귀만 지킨다.
+
+---
+
+## 3. Track 1 — High-Performance Vector Search + Incremental Indexing
+
+### 목표
+- 50k~100k 노드에서도 hybrid 검색 p50 < 40~60ms
+- 배경 인덱싱으로 사용자가 인제스트 후 바로 검색 가능하게
+- 기존 hybrid (FTS5 + vector) + `context_quality` 신호 유지
+
+### 현재 상태
+- `lattice_brain/graph/retrieval_vector.py` : brute-force + vector freshness
+- `hybrid_search` 존재
+- PERFORMANCE.md 기준 5k에서 벡터 p50 ~1.7s
+
+### 구현 단계
+
+#### 1.1 벡터 인덱스 추상화 레이어 도입
+- `lattice_brain/graph/vector_index/` 패키지 신설
+- Protocol 정의:
+  ```python
+  class VectorIndex(Protocol):
+      def add(self, id: str, vector: np.ndarray, metadata: dict) -> None: ...
+      def search(self, query: np.ndarray, top_k: int, filter: dict | None = None) -> list[ScoredId]: ...
+      def remove(self, id: str) -> None: ...
+      def rebuild(self) -> None: ...
+      def stats(self) -> IndexStats: ...
+  ```
+- 기본 구현체 2개:
+  - `BruteForceIndex` (기존 로직 이전, fallback)
+  - `HnswIndex` (신규)
+
+#### 1.2 HNSW 엔진 선택 & 통합
+**권장 경로 (우선순위)**:
+1. **단기 (가장 빠름)**: `usearch` 또는 `hnswlib` Python 바인딩으로 프로토타입. Apple Silicon에서 잘 돌아가는지 확인.
+2. **중기 (권장 최종)**: 순수 Rust HNSW + Python binding (또는 Tauri 쪽 native).  
+   후보: `usearch`(이미 Rust 코어), `minimemory`, `leann-core`, `monavec` 계열.  
+   SQLite 파일과 별도로 `.hnsw` 또는 메모리맵 인덱스를 Brain 디렉터리에 둔다.
+3. Quantization (int8 / binary) 옵션을 처음부터 넣어서 메모리 절약.
+
+#### 1.3 Incremental / Background Indexing
+- 인제스트 파이프라인에 `vector_job` 큐 추가 (이미 `/api/ingestion/jobs` 패턴 존재).
+- 노드 upsert 시 “pending embed” 상태로 표시 → 백그라운드 워커가 임베딩 + 인덱스 추가.
+- `vector_freshness` API를 더 세분화: `embedded / pending / stale / total`.
+- 재인덱싱은 전체 rebuild와 incremental upsert 둘 다 지원.
+
+#### 1.4 Hybrid Search 고도화
+- Reciprocal Rank Fusion (RRF) 또는 학습 가능한 fusion weight를 query class별로 적용.
+- graph traversal 결과를 candidate expansion으로 사용 (이미 neighbors/traverse 존재).
+- `context_quality` 점수에 vector freshness와 ANN recall 추정치를 반영.
+
+#### 1.5 완료 기준
+- [ ] 10k 합성 노드에서 hybrid p50 < 50ms
+- [ ] 배경 인덱싱이 켜진 상태에서 새 파일 인제스트 후 30초 이내 검색 가능
+- [ ] 기존 hybrid_search API 시그니처 호환 (breaking change 없음)
+- [ ] `docs/PERFORMANCE.md` 업데이트 + 벤치 스크립트 포함
+
+---
+
+## 4. Track 2 — Proactive Synthesis + Contradiction + Temporal
+
+### 목표
+Brain이 수동 검색 도구가 아니라 **스스로 관찰하고 제안하는 존재**가 된다.
+
+### 현재 상태
+- `lattice_brain/graph/proactive.py` : 읽기 전용 (duplicate, contradiction, quality report)
+- Brain Brief, MultiAgentOrchestrator, workflow_engine 존재
+
+### 구현 단계
+
+#### 2.1 Contradiction Detection을 쓰기 가능한 루프로
+- 기존 읽기 전용 감지를 **제안 생성**까지 확장.
+- 새 사실 인제스트 시 기존 관련 노드와 비교 → `ContradictionProposal` 생성.
+- UI: “이 두 기억은 모순됩니다. 어떻게 할까요?” (유지 / 새 사실로 교체 / 둘 다 유지하고 시간 범위 표시)
+
+#### 2.2 Temporal Model 도입
+- 노드/엣지에 `valid_from`, `valid_to`, `superseded_by` 필드 추가 (스키마 확장).
+- 쿼리 API: `as_of(timestamp)` → 그 시점의 유효 그래프 슬라이스.
+- “2025년 6월에 내가 알고 있던 프로젝트 상태” 같은 질문 지원.
+
+#### 2.3 Background Synthesis Jobs
+- 주기적 또는 이벤트 기반 (새 노드 N개 추가 후) synthesis 실행.
+- 출력물:
+  - Brain Brief 강화 (주간/월간 요약)
+  - 새로운 상위 개념 노드 제안
+  - “자주 같이 등장하지만 연결이 없는” 후보 엣지 제안
+- 모두 Change Governor를 통해 제안으로만 들어온다.
+
+#### 2.4 Memory Decay & Consolidation (선택적이지만 강력)
+- 접근 빈도 + 시간 경과로 importance score 계산.
+- 낮은 점수 에피소딕 기억은 상위 semantic 노드로 합쳐지는 “수면” 프로세스 시뮬레이션.
+- 사용자에게 “Brain이 정리 중입니다” 신호를 정직하게 보여줌.
+
+#### 2.5 완료 기준
+- [ ] 모순이 발생하면 제안이 자동 생성되고 UI에서 리뷰 가능
+- [ ] `as_of` 쿼리가 동작하고 테스트 커버
+- [ ] Brain Brief가 proactive 제안을 포함
+- [ ] 모든 쓰기는 proposal 경로
+
+---
+
+## 5. Track 3 — Multi-modal as First-Class Citizen
+
+### 목표
+이미지·오디오·(간단)비디오가 텍스트와 동등한 기억 단위가 된다.
+
+### 현재 상태
+- 스키마에 IMAGE / IMAGE_TEXT / CONTAINS_IMAGE 존재
+- discovery에 PIL + pytesseract OCR 일부
+- `allow_multimodal` 플래그 기본 false
+- vision embedding / retrieval 경로 미비
+
+### 구현 단계
+
+#### 3.1 임베딩 파이프라인 확장
+- `embedding_providers.py`에 vision 프로바이더 추가 (로컬: MLX 비전 모델 또는 CLIP 계열, 클라우드: 선택적).
+- 텍스트 임베딩과 같은 차원으로 맞추거나, 멀티모달 공통 공간 사용.
+- 이미지 노드에 `embedding` + `ocr_text` + `caption` (비전 LLM 생성) 저장.
+
+#### 3.2 인제스트 라우팅
+- 파일 MIME에 따라 IMAGE / AUDIO 노드 생성.
+- 오디오: 로컬 whisper 계열 또는 시스템 전사 → 텍스트 + 타임스탬프 청크.
+- 비디오: 키프레임 추출 + 자막/전사 (1차로 키프레임만 해도 충분).
+
+#### 3.3 Retrieval 통합
+- hybrid_search가 이미지 노드도 반환.
+- “지난달 제주에서 찍은 사진 중 회의 관련” 같은 쿼리가 그래프 + 벡터로 동작.
+- UI Evidence 패널에 이미지 썸네일 + 캡션 + 출처 표시.
+
+#### 3.4 완료 기준
+- [ ] 이미지 폴더 인제스트 → 검색 가능
+- [ ] 비전 캡션이 그래프에 들어가고 hybrid에 기여
+- [ ] `allow_multimodal=true`일 때만 동작 (기본값 유지 가능)
+- [ ] 추출 품질 점수가 이미지에도 적용
+
+---
+
+## 6. Track 4 — Personal Ontology + Agent-Native Workspace OS
+
+### 목표
+Brain이 “나”를 알고, 에이전트가 워크스페이스를 실제로 조작·진화시킬 수 있게 한다.
+
+### 구현 단계
+
+#### 4.1 Personal Ontology / Self-Model
+- 새로운 노드 타입 또는 특수 서브그래프: `Self`, `Preference`, `Decision`, `Habit`, `Relationship`.
+- 대화와 파일에서 자동 추출 → 제안으로만 추가.
+- 에이전트 컨텍스트에 “현재 Self-Model 요약”을 항상 주입할 수 있는 API.
+- 사용자는 Self-Model을 직접 편집·삭제 가능 (ownership).
+
+#### 4.2 Agent-Native Workspace
+- AgentRuntime이 파일 생성/수정/이동/삭제 제안을 더 안정적으로 수행.
+- 장기 실행 세션: “이 프로젝트를 정리해줘” → 여러 단계 proposal 체인.
+- Workspace OS (`workspace_os.py`)와 더 깊은 통합: 에이전트가 폴더 구조를 Brain 관점으로 재구성 제안.
+- 약한 로컬 모델(Gemma 등)에서도 “파일 생성까지” 가는 성공률을 높이는 프롬프트/툴 설계 (이미 관심 영역).
+
+#### 4.3 완료 기준
+- [ ] Self-Model이 생성되고 채팅 컨텍스트에 반영
+- [ ] 에이전트가 파일 작업을 proposal로 안정적으로 수행
+- [ ] 사용자가 Self-Model을 투명하게 볼 수 있음
+
+---
+
+## 7. Track 5 — Interop + Selective Brain Network
+
+### 목표
+기존 지식 도구와 연결하고, 선택적으로 다른 Brain과 안전하게 공유.
+
+### 구현 단계
+
+#### 5.1 Interop Bridges (우선순위 높은 것부터)
+1. **Obsidian** — vault 폴더를 감시하거나 수동 동기. 마크다운 → 노드 + 백링크를 엣지로.
+2. **Notion** — export 또는 API (opt-in) 인제스트.
+3. **이메일/캘린더** — 로컬 파일 또는 시스템 권한으로 (macOS 중심).
+4. **Git** — 커밋 메시지 + 변경 파일을 프로젝트 기억으로.
+
+모두 기존 IngestionPipeline 단일 게이트를 통과.
+
+#### 5.2 Selective Encrypted Brain Network
+- `.latticebrain` 아카이브의 확장: 전체 Brain이 아니라 **선택적 subgraph + provenance** 내보내기.
+- 수신 측은 “제안으로만” 받아들이고, 출처를 명확히 표시.
+- 암호화는 기존 아카이브 메커니즘 재사용 + 수신자 공개키(선택).
+- UI: “이 결정 그래프만 공유” 같은 단위.
+
+#### 5.3 완료 기준
+- [ ] Obsidian vault → Brain 인제스트가 동작
+- [ ] subgraph 공유 → 상대방 Brain에 proposal로 들어옴
+- [ ] 네트워크 기능은 기본 꺼짐 (opt-in)
+
+---
+
+## 8. 권장 실행 일정 (11.1.0 단일 릴리즈 기준)
+
+가정: 집중 작업 기준 3~5주 스프린트.
+
+| 주차 | 주요 포커스 | 산출물 |
+|------|-------------|--------|
+| Week 1 | Track 1 전체 (벡터 추상화 + HNSW 프로토타입 + 배경 인덱싱) | 벤치 통과, hybrid API 호환 |
+| Week 2 | Track 2 (모순 제안 + temporal 스키마 + synthesis job) + Track 1 안정화 | proactive UI 초안 |
+| Week 3 | Track 3 (비전 임베딩 + 이미지 인제스트 + retrieval) + Track 4 스키마 | 이미지 검색 가능 |
+| Week 4 | Track 4 구현 + Track 5 브릿지 (Obsidian 우선) | Self-Model + Obsidian |
+| Week 5 | 통합, 폴리시, 문서, 릴리즈 노트, 벤치 재측정 | v11.1.0 태그 |
+
+병렬로 돌릴 수 있는 부분은 최대한 병렬.  
+막히는 지점(특히 Rust 바인딩 성능)은 Python 바인딩으로 먼저 출시하고 다음 마이너에서 네이티브로 교체해도 된다.
+
+---
+
+## 9. 릴리즈 전략 & 문서 게이트
+
+- 브랜치: `release/v11.1.0` 또는 `feature/product-intelligence`
+- 모든 트랙이 머지된 후 **한 번의** 통합 테스트 + 성능 벤치 후 태그.
+- `AGENTS.md`, `ARCHITECTURE.md`, `FEATURE_STATUS.md`, `RELEASE_NOTES_v11.1.0.md` 동시 업데이트.
+- CHANGELOG에는 “Product Intelligence Layer”로 포지셔닝.
+- 기존 100% 커버리지 게이트는 유지하되, 신규 코드에 대한 과도한 커버리지 강요는 하지 않는다 (회귀만).
+
+---
+
+## 10. 위험 요소와 완화
+
+| 위험 | 완화 |
+|------|------|
+| HNSW 도입으로 검색 품질(recall) 하락 | 기본 fallback을 brute-force로 두고, ANN은 `approx=true` 옵션. recall 벤치 필수. |
+| 멀티모달 임베딩 차원이 텍스트와 다름 | 공통 공간 모델 사용 또는 별도 인덱스 + late fusion. |
+| Temporal 스키마 변경으로 기존 Brain 깨짐 | 마이그레이션 스크립트 + `valid_from` 기본값을 created_at으로. |
+| 에이전트가 너무 공격적으로 제안 | PermissionMode + Change Governor 강화. 기본은 보수적. |
+| 11.1.0 범위가 너무 큼 | Track 5의 Brain Network는 “프로토타입 + 플래그”로 축소 가능. Interop는 Obsidian만 필수. |
+
+---
+
+## 11. 성공의 정의 (v11.1.0 완료 시)
+
+사용자가 다음을 체감해야 한다:
+
+1. **빠르다** — 큰 Brain에서도 검색이 즉각적이다.
+2. **살아있다** — Brain이 모순을 알려주고, 요약을 해주고, 연결을 제안한다.
+3. **모든 것을 기억한다** — 사진도, 메모도, 대화도 같은 그래프에 있다.
+4. **나를 안다** — 내 선호와 결정 이력이 에이전트 행동에 반영된다.
+5. **연결된다** — Obsidian 등 기존 도구와 자연스럽게 이어지고, 원하면 선택적으로 공유할 수 있다.
+
+이것이 “Model is the voice, Brain is the lifelong asset”을 제품 수준에서 완성한 상태다.
+
+---
+
+## 12. 다음 액션 (바로 시작)
+
+1. 이 문서를 `docs/v11.1.0_PRODUCT_INTELLIGENCE_PLAN.md`로 커밋.
+2. Track 1부터 이슈/브랜치 생성.
+3. 벡터 인덱스 Protocol + BruteForce 이전 작업부터 착수.
+4. 매주 금요일에 “체감 데모” 기준으로 진행 상황 점검 (커버리지 %가 아니라).
+
+---
+
+**문서 끝.**  
+이 계획대로면 v11.1.0은 “테스트와 보안의 LatticeAI”에서 **“실제로 쓰는 지능형 Digital Brain”**으로의 전환점이 된다.

package/lattice_brain/__init__.py

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

package/lattice_brain/graph/_kg_contract.py

@@ -173,6 +173,17 @@ class KnowledgeGraphCore:
         """``{status, pending_items, total_items, detail}`` — never raises."""
         raise NotImplementedError
 
+    # ── retrieval_reads.py: 1-hop walk (hybrid candidate expansion) ──────────
+    def neighbors(
+        self,
+        node_id: str,
+        *,
+        allowed_workspaces: Any = None,
+        include_legacy_global: bool = False,
+        as_of: Any = None,
+    ) -> Dict[str, Any]:
+        raise NotImplementedError
+
     # ── retrieval_reads.py: workspace scoping ────────────────────────────────
     def filter_scoped_nodes(
         self,

package/lattice_brain/graph/curator.py

@@ -196,7 +196,7 @@ def extract_topic_candidates(
         seen_in_doc: Set[str] = set()
         for term in bag:
             if term in seen_in_doc:
-                continue
+                continue  # pragma: no cover — unreachable: bag is list(set(...)), already deduplicated
             seen_in_doc.add(term)
             counts[term] = counts.get(term, 0.0) + weight
             sources.setdefault(term, []).append(str(doc.get("id") or ""))

package/lattice_brain/graph/fusion.py

@@ -28,7 +28,7 @@ from __future__ import annotations
 import json
 import os
 import re
-from typing import Any, Dict, Mapping, Optional
+from typing import Any, Callable, Dict, List, Mapping, Optional, Sequence, Tuple
 
 from ..quiet import quiet
 
@@ -36,6 +36,26 @@ QUERY_CLASSES = ("fact", "code", "person", "recency")
 
 FUSION_WEIGHTS_ENV = "LATTICEAI_FUSION_WEIGHTS"
 
+# ── fusion strategy (v11.1.0) ────────────────────────────────────────────────
+# Linear alpha fusion needs the two channels' scores to be comparable. They
+# are not: the lexical channel scores 1/rank while the vector channel scores a
+# max-normalized cosine, so a query where every cosine lands near 0.9 flattens
+# the vector channel to noise. Reciprocal Rank Fusion ignores score magnitudes
+# entirely and fuses *positions*, which is exactly the property that survives
+# incomparable scales.
+#
+# It is opt-in, per query class, and off everywhere by default: alpha fusion
+# is what every existing ranking assertion in this repo describes, and a
+# ranking change dressed up as a bug fix is how retrieval quality regressions
+# get shipped. Turn it on with LATTICEAI_FUSION_STRATEGY=rrf (all classes) or
+# a JSON object like {"code": "rrf"} (per class).
+FUSION_STRATEGY_ENV = "LATTICEAI_FUSION_STRATEGY"
+FUSION_STRATEGIES = ("alpha", "rrf")
+DEFAULT_FUSION_STRATEGY: Dict[str, str] = dict.fromkeys(QUERY_CLASSES, "alpha")
+#: The smoothing constant from the original RRF paper (Cormack et al., 2009).
+#: Larger k flattens the curve, so rank 1 wins by less.
+DEFAULT_RRF_K = 60
+
 # Per-class fusion weights. "fact" mirrors the pre-fusion-gate defaults
 # (SearchService DEFAULT_HYBRID_WEIGHTS + graph-layer alpha=0.6) so the
 # fallback class introduces zero behavioral drift.
@@ -145,16 +165,163 @@ def fusion_weight_table(
     return table
 
 
+def _env_strategy_overrides() -> Dict[str, str]:
+    """Parse ``LATTICEAI_FUSION_STRATEGY`` → per-class strategy overrides.
+
+    Two accepted forms: a bare strategy name (``rrf``) applies to every class,
+    a JSON object (``{"code": "rrf"}``) applies per class. Anything else —
+    a typo, malformed JSON, an unknown strategy — is ignored rather than
+    raising, so a bad env var degrades to the default fusion instead of
+    taking every search down.
+    """
+    raw = os.getenv(FUSION_STRATEGY_ENV, "").strip()
+    if not raw:
+        return {}
+    if raw.lower() in FUSION_STRATEGIES:
+        return dict.fromkeys(QUERY_CLASSES, raw.lower())
+    try:
+        payload = json.loads(raw)
+    except (ValueError, TypeError):
+        return {}
+    if not isinstance(payload, dict):
+        return {}
+    return {
+        str(cls): str(value).lower()
+        for cls, value in payload.items()
+        if cls in DEFAULT_FUSION_STRATEGY and str(value).lower() in FUSION_STRATEGIES
+    }
+
+
+def fusion_strategy_table(
+    overrides: Optional[Mapping[str, str]] = None,
+) -> Dict[str, str]:
+    """Full per-class strategy table: defaults ← env override ← caller."""
+    table = dict(DEFAULT_FUSION_STRATEGY)
+    for source in (_env_strategy_overrides(), overrides or {}):
+        for cls, value in source.items():
+            if cls in table and str(value).lower() in FUSION_STRATEGIES:
+                table[cls] = str(value).lower()
+    return table
+
+
+def rrf_score(rank: int, *, k: int = DEFAULT_RRF_K) -> float:
+    """One channel's contribution for an item it ranked at ``rank`` (1-based)."""
+    return 1.0 / (int(k) + max(1, int(rank)))
+
+
+def rrf_fuse(
+    rankings: Mapping[str, Sequence[str]],
+    *,
+    k: int = DEFAULT_RRF_K,
+    weights: Optional[Mapping[str, float]] = None,
+) -> Dict[str, float]:
+    """Reciprocal Rank Fusion over per-channel id rankings.
+
+    ``rankings`` maps a channel name to its ids in rank order (best first).
+    An id absent from a channel simply contributes nothing from it — RRF has
+    no notion of a "missing score" to guess at, which is the other reason it
+    survives channels that fail independently.
+
+    ``weights`` optionally scales a channel's contribution (a channel missing
+    from the mapping weighs 1.0). Deterministic and pure.
+    """
+    fused: Dict[str, float] = {}
+    for channel, ordered in rankings.items():
+        weight = 1.0 if weights is None else float(weights.get(channel, 1.0))
+        for rank, item_id in enumerate(ordered, start=1):
+            fused[item_id] = fused.get(item_id, 0.0) + weight * rrf_score(rank, k=k)
+    return fused
+
+
+# ── graph traversal candidate expansion (v11.1.0) ────────────────────────────
+# Both retrieval channels can only return what they matched. A note that
+# never says "postgres" but is one CONTAINS edge away from the one that does
+# is unreachable by either — and it is often the answer. Expansion walks one
+# hop out from the top hits and offers those neighbours as candidates.
+#
+# It is capped, off by default, and reports its own counts, because the
+# failure mode is dilution: an unbounded expansion turns a precise answer into
+# a tour of the graph.
+GRAPH_EXPANSION_ENV = "LATTICEAI_GRAPH_EXPANSION"
+DEFAULT_EXPANSION_SEEDS = 3
+DEFAULT_EXPANSION_CAP = 5
+#: Expanded candidates inherit a damped share of their seed's score: they are
+#: related to a hit, they are not themselves a hit.
+EXPANSION_DECAY = 0.5
+
+
+def graph_expansion_enabled() -> bool:
+    """True when ``LATTICEAI_GRAPH_EXPANSION`` opts in (default: off)."""
+    raw = os.getenv(GRAPH_EXPANSION_ENV, "").strip().lower()
+    return raw in {"1", "true", "yes", "on"}
+
+
+def expand_with_neighbors(
+    seeds: Sequence[Tuple[str, float]],
+    neighbors_fn: Callable[[str], Any],
+    *,
+    exclude: Optional[Sequence[str]] = None,
+    cap: int = DEFAULT_EXPANSION_CAP,
+) -> Tuple[List[Dict[str, Any]], Dict[str, Any]]:
+    """One-hop neighbours of ``seeds`` as extra candidates + an honest report.
+
+    ``seeds`` is ``[(node_id, score)]`` best first; ``neighbors_fn`` is the
+    store's ``neighbors``. Returns ``(candidates, report)`` where each
+    candidate carries its originating seed and a decayed score, and the report
+    states how many seeds were walked, how many candidates were kept, and
+    whether the cap bit. A neighbour lookup that fails is skipped and counted,
+    never raised: expansion is an optimization, not a dependency.
+    """
+    known = {str(item) for item in (exclude or ())}
+    cap = max(0, int(cap))
+    candidates: List[Dict[str, Any]] = []
+    failures = 0
+    for seed_id, seed_score in seeds:
+        if len(candidates) >= cap:
+            break
+        try:
+            payload = neighbors_fn(seed_id) or {}
+        except Exception:  # noqa: BLE001 — a bad seed must not fail the search
+            failures += 1
+            continue
+        for node in payload.get("neighbors") or []:
+            node_id = str(node.get("id") or "")
+            if not node_id or node_id in known:
+                continue
+            known.add(node_id)
+            candidates.append(
+                {
+                    "node": node,
+                    "seed": str(seed_id),
+                    "score": round(float(seed_score) * EXPANSION_DECAY, 6),
+                }
+            )
+            if len(candidates) >= cap:
+                break
+    report = {
+        "enabled": True,
+        "seeds": len(seeds),
+        "added": len(candidates),
+        "cap": cap,
+        "truncated": len(candidates) >= cap,
+        "failed_seeds": failures,
+    }
+    return candidates, report
+
+
 def fusion_profile(
     query: Any,
     *,
     overrides: Optional[Mapping[str, Mapping[str, float]]] = None,
+    strategies: Optional[Mapping[str, str]] = None,
 ) -> Dict[str, Any]:
     """Classify ``query`` and return its resolved fusion weights.
 
     Returns ``{"query_class": str, "weights": {keyword, vector, graph},
-    "alpha": float}``. ``weights`` feeds the three-channel service fusion;
-    ``alpha`` feeds the two-channel graph-layer fusion.
+    "alpha": float, "strategy": "alpha"|"rrf"}``. ``weights`` feeds the
+    three-channel service fusion; ``alpha`` feeds the two-channel graph-layer
+    fusion; ``strategy`` selects *how* those channels combine and is
+    ``"alpha"`` for every class unless configured otherwise.
     """
     query_class = classify_query(query)
     table = fusion_weight_table(overrides)
@@ -170,14 +337,28 @@ def fusion_profile(
             "graph": resolved["graph"],
         },
         "alpha": resolved["alpha"],
+        "strategy": fusion_strategy_table(strategies)[query_class],
     }
 
 
 __all__ = [
+    "DEFAULT_EXPANSION_CAP",
+    "DEFAULT_EXPANSION_SEEDS",
+    "DEFAULT_FUSION_STRATEGY",
     "DEFAULT_FUSION_WEIGHTS",
+    "DEFAULT_RRF_K",
+    "EXPANSION_DECAY",
+    "FUSION_STRATEGIES",
+    "FUSION_STRATEGY_ENV",
     "FUSION_WEIGHTS_ENV",
+    "GRAPH_EXPANSION_ENV",
     "QUERY_CLASSES",
     "classify_query",
+    "expand_with_neighbors",
     "fusion_profile",
+    "fusion_strategy_table",
     "fusion_weight_table",
+    "graph_expansion_enabled",
+    "rrf_fuse",
+    "rrf_score",
 ]