ltcai 11.0.1 → 11.2.0

package/docs/LAYOUT_REBUILD_SPEC.md

@@ -5,6 +5,13 @@
 이 문서의 모든 파일 경로와 줄 번호는 실제로 열어서 확인한 것이다.
 추측한 경로는 한 줄도 없다.
 
+> **증거 기준선 안내 (v11.2.0 기준).** 이 설계서가 인용하는
+> `output/release/v10.6.3/screenshots/` 는 **더 이상 리포에 없다** — 릴리스 증거는
+> v11.0.0 부터만 보관한다(`output/release/v11.0.0` · `v11.0.1` · `v11.1.0`).
+> 따라서 아래의 "이전 캡처와 해시 대조" 절차는 그대로는 재현할 수 없다.
+> 문서는 당시 측정값을 기록한 사료로 남기고, 지금 다시 채점한다면 기준선은
+> **가장 최근 릴리스의 `output/release/<버전>/screenshots/`** 로 바꿔서 읽는다.
+
 ---
 
 ## 0. 이 재구성이 존재하는 이유
@@ -706,7 +713,8 @@ npm run frontend:openapi:check            # OpenAPI drift 게이트
 
 ### 7.1 릴리스 캡처 12개 화면 전부 변경 — **24점** (화면당 2점)
 
-**확인 명령:**
+**확인 명령:** (기준선 경로는 문서 상단 안내대로 최신 릴리스 디렉터리로 바꿔 읽는다 —
+`output/release/v10.6.3/` 는 리포에서 사라졌다.)
 ```
 npm run build:assets
 LTCAI_RELEASE_EVIDENCE_DIR=/tmp/lattice-after npm run release:evidence

package/docs/ONBOARDING.md

@@ -1,6 +1,6 @@
 # Lattice AI Onboarding
 
-Current release: **11.0.1 — Both Branches**.
+Current release: **11.2.0 — All Systems On**.
 
 The first-run goal is a five-minute path from "I opened the app" to "my Brain
 has a source, a question, and proof." This page is the product contract behind

package/docs/OPERATIONS.md

@@ -1,4 +1,4 @@
-# Lattice AI — Operations Guide (v11.0.1)
+# Lattice AI — Operations Guide (v11.2.0)
 
 > **Status: canonical** — kept in sync with the current release. Storage layout
 > below reflects the SQLite live Brain store and workspace scoping, not the

package/docs/PERFORMANCE.md

@@ -110,6 +110,10 @@ Methodology, and what it does not cover:
 - Latency and memory are measured in separate passes. tracemalloc roughly
   triples Python allocation cost, so timing under it would measure the
   profiler — the `peak MB` column comes from one extra traced query.
+- `peak MB` counts **Python** allocations only. hnswlib keeps its graph in C++
+  memory, which tracemalloc cannot see, so that column understates HNSW by the
+  size of the graph itself. Read it as "what the query costs the interpreter",
+  not as the process's resident size.
 - `first ms` is the *first* query after the corpus changed. For `hnsw` that is
   where the graph gets built and the `.hnsw` sidecar written; for the other two
   it is an ordinary query.
@@ -135,27 +139,27 @@ Run it:
 ### Measured, 2026-08-10 — 10 000 vectors, 30 queries, top_k 10
 
 macOS 27 (arm64, Apple Silicon), Python 3.14.5, SQLite 3.53.1,
-hnswlib 0.8.0, uncapped candidates, corpus build 2.12 s.
+hnswlib 0.8.0, uncapped candidates, corpus build 2.19 s.
 
 | backend | p50 ms | p95 ms | first ms | peak MB | recall@10 | hybrid p50 ms |
 |-----------|-------:|-------:|---------:|--------:|----------:|--------------:|
-| brute     | 288.89 | 291.95 |   290.68 |   39.72 |    1.000  |        296.63 |
-| quantized | 639.47 | 645.93 |   653.31 |   38.38 |    0.987  |        639.83 |
-| hnsw      |  21.53 |  22.11 |   795.84 |    0.74 |    0.953  |         24.37 |
+| brute     | 293.25 | 299.31 |   293.91 |   39.72 |    1.000  |        299.17 |
+| quantized | 640.58 | 650.15 |   636.87 |   38.38 |    0.987  |        653.33 |
+| hnsw      |   7.01 |   7.50 |   799.95 |    0.05 |    0.953  |         10.07 |
 
 What the table says, plainly:
 
-- **The default is exact and slow.** 289 ms per query at 10k, and hybrid
-  inherits nearly all of it (297 ms) — the vector channel *is* the cost.
-- **HNSW meets the 11.1.0 target and prices it.** Hybrid p50 **24.4 ms** at 10k
-  (target: < 50 ms), a 12x improvement, in exchange for **4.7% of the exact
+- **The default is exact and slow.** 293 ms per query at 10k, and hybrid
+  inherits nearly all of it (299 ms) — the vector channel *is* the cost.
+- **HNSW meets the 11.1.0 target and prices it.** Hybrid p50 **10.1 ms** at 10k
+  (target: < 50 ms), a 30x improvement, in exchange for **4.7% of the exact
   top-10 going missing**. That is the trade, stated as a number rather than as
-  the word "approximate". Its 0.74 MB peak is the two-phase lookup: it reads
-  only the ten rows it returns, where the exact scan reads all 10 000.
-- **The 796 ms first query is the graph build**, paid once per index generation
-  and then persisted to the `.hnsw` sidecar. Any write to `vector_embeddings`
-  invalidates the fingerprint and buys that cost again, which is why `brute`
-  stays the default for a continuously-ingesting brain.
+  the word "approximate".
+- **The 800 ms first query is the graph build**, paid once per index generation
+  and then persisted to the `.hnsw` sidecar (and held in memory for the rest of
+  the process). Any write to `vector_embeddings` invalidates the fingerprint
+  and buys that cost again, which is why `brute` stays the default for a
+  continuously-ingesting brain.
 - **Quantized is currently the wrong choice on every axis.** ~2.2x the latency
   for 0.987 recall, and its RAM advantage does not materialise (38.4 vs
   39.7 MB): the exact scan already feeds the index in bounded batches, so
@@ -163,16 +167,65 @@ What the table says, plainly:
   It ships as an honest, exhaustive backend and as the representation a held
   cross-query index would need. It is not a recommendation.
 
+### Measured, 2026-08-10 — 50 000 vectors, 15 queries, top_k 10
+
+Same machine and settings; corpus build 11.19 s.
+
+| backend | p50 ms | p95 ms | first ms | peak MB | recall@10 | hybrid p50 ms |
+|-----------|--------:|--------:|---------:|--------:|----------:|--------------:|
+| brute     | 1515.31 | 1522.94 |  1520.89 |  194.92 |    1.000  |       1514.75 |
+| quantized | 3254.76 | 3275.69 |  3253.54 |  195.05 |    0.967  |       3441.13 |
+| hnsw      |   35.58 |   38.19 |  6114.60 |    0.04 |    0.987  |         43.90 |
+
+- **The exact scan is linear and unusable at this size**: 1.5 s per query, and
+  ~195 MB of Python allocation to score one question.
+- **HNSW still clears the 50 ms budget at 5x the target corpus** — hybrid p50
+  43.9 ms — and its recall here is 0.987, higher than the 10k run's 0.953
+  (15 queries is a small sample; treat the two as "around 0.95–0.99", not as a
+  trend).
+- **The remaining HNSW cost is not the search.** 7 ms at 10k → 36 ms at 50k is
+  suspiciously linear for a graph index, and it is: every query first runs the
+  freshness check (`SELECT COUNT(*), MAX(indexed_at) FROM vector_embeddings
+  WHERE embedding_model=? AND embedding_dim=?`), which has no covering index
+  and walks the table. A named follow-up, not a mystery: an index on
+  `(embedding_model, embedding_dim)` would remove it. The budget is met either
+  way, so it was not worth a schema change in this release.
+- **The 6.1 s first query is the 50k graph build.** It is paid once per index
+  generation, and the sidecar means a restart does not pay it again.
+
+### A measurement mistake worth keeping
+
+The first 50k run reported HNSW recall of **0.18** and was wrong. The default
+candidate cap (10 000) was still in force, so the "exact" baseline had scored
+only the newest 10 000 of 50 000 rows while HNSW searched all of them — the
+disagreement was the baseline's blind spot, not the ANN's error. The bench now
+lifts the cap by default and prints a `trunc` column. Recorded here because
+the failure mode is generic: *any* recall number measured against a truncated
+baseline is measuring the truncation.
+
+### Not measured
+
+- **100k+ vectors.** Nothing is claimed beyond the 50k run above.
+- **sqlite-vec ANN.** The optional `ann` extra was not installed, so
+  `vector_search_backend` reported `bruteforce-cosine` throughout. Its numbers
+  are unknown, not zero.
+- **A real embedding provider.** Everything here uses the deterministic hash
+  embedder. With a model- or network-backed embedder, query-embedding cost
+  moves into the foreground and these ratios change.
+- **Resident process memory.** See the tracemalloc caveat above: the HNSW graph
+  lives outside Python's allocator and is not in the `peak MB` column.
+
 ## Observations
 
 - Keyword `search()` / `context_for_query()` stay low-millisecond thanks to
   the FTS5 trigram index; they are not the scaling bottleneck.
 - `traverse(depth=2)` cost grows with edge fan-out (synthetic corpus creates
   dense shared-concept hubs); p95 is ~5 ms at 500 sources and ~16 ms at 5000.
-- `vector_search()` is a brute-force scan over every stored embedding
-  (O(index size) per query). It is the dominant cost at scale and the first
-  candidate for an ANN/pruning optimization if vector recall becomes a hot
-  path. The profiler caps vector queries at 10 for this reason.
+- `vector_search()` on the default backend is a brute-force scan over every
+  stored embedding (O(index size) per query). It is the dominant cost at scale
+  — which is what the 11.1.0 backend table above measures, and what
+  `LATTICEAI_VECTOR_INDEX=hnsw` addresses. `profile_kg.py` still caps vector
+  queries at 10 for this reason.
 - `rebuild_vector_index(full=True)` embeds documents and chunks with the hash
   embedder; with a real embedding provider expect this phase to be slower by
   the provider's per-call latency times the item count.

package/docs/TRUST_MODEL.md

@@ -1,6 +1,6 @@
 # Lattice AI Trust Model
 
-Current release: **11.0.1 — Both Branches**.
+Current release: **11.2.0 — All Systems On**.
 
 Lattice AI is local-first, explicit about external communication, and honest
 when a capability is unavailable.

package/docs/WHY_LATTICE.md

@@ -1,6 +1,6 @@
 # Why Lattice AI Exists
 
-Current release: **11.0.1 — Both Branches**.
+Current release: **11.2.0 — All Systems On**.
 
 **Lattice AI is a local-first Digital Brain that keeps your knowledge durable
 across any AI model.**

package/docs/architecture.md

@@ -130,8 +130,12 @@ hardware scan
   -> download/install/load/verify
 ```
 
-The current default recommendation family is Gemma 4. Qwen3-VL and Llama 4
-remain current multimodal alternatives.
+The current default recommendation family is Gemma 4. Qwen3.6 and Qwen3.5 are
+the current multimodal alternatives; GPT-OSS 20B and LFM2.5 2.6B fill the
+general-purpose and ultralight tiers as text-only models. Superseded families
+(Qwen3-VL, Llama 4, Qwen2.5-VL, Llama 3.2 Vision) stay in the capability
+registry as *recognised* entries so already-downloaded weights keep working,
+but they never appear in the catalog or a download path. See MODEL_POLICY.md.
 
 ## Modes
 

package/docs/kg-schema.md

@@ -1,6 +1,6 @@
 # Knowledge Graph Schema
 
-Current release: **11.0.1 — Both Branches**.
+Current release: **11.2.0 — All Systems On**.
 
 명세 출처: `lattice_ai_full_spec.pptx` 슬라이드 20·21·22
 구현: `lattice_brain/graph/schema.py`

package/lattice_brain/__init__.py

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

package/lattice_brain/embeddings.py

@@ -8,7 +8,7 @@ import os
 import re
 import struct
 from dataclasses import dataclass
-from typing import Any, Dict, Iterable, List, Optional
+from typing import Iterable, List
 
 DEFAULT_EMBEDDING_DIM = int(os.getenv("LATTICEAI_VECTOR_DIM", "384"))
 EMBEDDING_MODEL_ID = f"lattice-local-hash-v1:{DEFAULT_EMBEDDING_DIM}"
@@ -97,40 +97,15 @@ class LocalEmbeddingModel:
         return list(struct.unpack(f"<{count}f", payload[: count * 4]))
 
 
-# --- Large candidate #2 slice: multimodal (vision) stubs ---
-# Schema already defines IMAGE / IMAGE_TEXT / CONTAINS_IMAGE.
-# These stubs allow ingestion + retrieval paths to carry image signals without
-# requiring heavy deps at core. Real impl can swap in local vision (e.g. via
-# ollama vision or onnx CLIP) behind the same interface.
-@dataclass(frozen=True)
-class VisionStub:
-    """Offline vision describe + embed stubs for multimodal Brain.
-
-    describe: returns a short textual caption derived from metadata/filename.
-    embed: produces a vector from image meta (size+format) + optional caption hash.
-    Later: replace with real embedding model that accepts image bytes/path.
-    """
-    dim: int = DEFAULT_EMBEDDING_DIM
-
-    def describe(self, path: str | None = None, meta: Optional[Dict[str, Any]] = None) -> str:
-        meta = meta or {}
-        w = meta.get("width") or meta.get("w") or "?"
-        h = meta.get("height") or meta.get("h") or "?"
-        fmt = meta.get("format") or meta.get("ext") or "img"
-        name = (path or "").split("/")[-1] or "image"
-        # deterministic caption stub (no external call)
-        return f"Image {name} ({fmt} {w}x{h})"
-
-    def embed_image(self, path: str | None = None, meta: Optional[Dict[str, Any]] = None, caption: str = "") -> List[float]:
-        meta = meta or {}
-        basis = f"{path or ''}|{meta.get('width',0)}x{meta.get('height',0)}|{meta.get('format','')}|{caption[:120]}"
-        # reuse text embedder for determinism (image content hash would be better with real vision)
-        model = LocalEmbeddingModel(dim=self.dim)
-        return model.embed(basis)
-
-
-def get_vision_embedder(dim: int | None = None) -> VisionStub:
-    return VisionStub(dim=dim or DEFAULT_EMBEDDING_DIM)
-
+# Removed in v11.1.0: ``VisionStub`` / ``get_vision_embedder``.
+#
+# They produced a "caption" (``Image pic.png (PNG 12x8)``) and an "image
+# embedding" (a hash of the filename and pixel dimensions) with no model
+# involved, and ``discovery_index`` stored both. Once in the graph neither was
+# distinguishable from something a vision model had actually said, which is the
+# one property a caption must have. The honest seam is now
+# :class:`lattice_brain.multimodal.MultimodalPorts`: a caption exists only when
+# a vision-language model produced it, an image vector only when a vision model
+# produced it, and their absence is recorded as an absence.
 
-__all__ = ["DEFAULT_EMBEDDING_DIM", "EMBEDDING_MODEL_ID", "LocalEmbeddingModel", "embedding_model_id", "VisionStub", "get_vision_embedder"]
+__all__ = ["DEFAULT_EMBEDDING_DIM", "EMBEDDING_MODEL_ID", "LocalEmbeddingModel", "embedding_model_id"]

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"]

package/lattice_brain/graph/discovery_index.py

@@ -111,40 +111,38 @@ class KnowledgeGraphLocalIndexMixin(_Core):
             meta["text_slides"] = len(slides_text)
             text = "\n\n".join(slides_text)
         elif category == "image":
-            from PIL import Image
+            text = self._extract_image_signals(path, meta, include_ocr=include_ocr)
+        return text[:200_000], meta
 
-            with Image.open(str(path)) as image:
-                meta.update(
-                    {
-                        "width": image.width,
-                        "height": image.height,
-                        "format": image.format,
-                        "mode": image.mode,
-                        "ocr_enabled": bool(include_ocr),
-                    }
-                )
-                if include_ocr:
-                    try:
-                        import pytesseract
+    def _extract_image_signals(
+        self, path: Path, meta: Dict[str, Any], *, include_ocr: bool
+    ) -> str:
+        """Dimensions, OCR text, and — only if a VLM exists — a caption.
 
-                        text = pytesseract.image_to_string(image)
-                        meta["ocr_chars"] = len(text)
-                    except (
-                        Exception
-                    ) as exc:  # pragma: no cover - depends on local OCR runtime
-                        meta["ocr_error"] = str(exc)
-                        text = ""
-                # Large candidate #2 slice: always attach vision stub describe for IMAGE node evidence
-                try:
-                    from ..embeddings import get_vision_embedder
-                    v = get_vision_embedder()
-                    cap = v.describe(str(path), meta)
-                    meta["vision_caption"] = cap
-                    if not text:
-                        text = cap  # fallback text signal for retrieval
-                except Exception:
-                    meta["vision_caption"] = meta.get("vision_caption") or f"image:{path}"
-        return text[:200_000], meta
+        Until v11.1.0 this path always attached a ``vision_caption`` built out
+        of the filename and the pixel dimensions (``Image pic.png (PNG 12x8)``)
+        and used it as the retrieval text. Nothing downstream could tell that
+        string apart from something a vision model had actually said about the
+        picture, so every screenshot in the graph carried a fake description.
+
+        Now the caption comes from the injected port and from nowhere else. A
+        picture with no OCR text and no model still gets indexed — under its
+        filename, which is a fact — and ``caption_status`` says why there is no
+        caption.
+        """
+        from ..multimodal import MultimodalPorts, extract_image_facts
+
+        ports = getattr(self, "multimodal_ports", None) or MultimodalPorts()
+        facts = extract_image_facts(str(path), ports=ports, ocr=include_ocr)
+        meta.update(facts.as_metadata())
+        meta["ocr_enabled"] = bool(include_ocr)
+        if facts.ocr_text:
+            meta["ocr_chars"] = len(facts.ocr_text)
+        if facts.ocr_status == "failed":
+            meta["ocr_error"] = facts.ocr_detail
+        if not facts.readable:
+            return ""
+        return facts.index_text() or path.name
 
     def _ensure_local_hierarchy(
         self,

package/lattice_brain/graph/fusion.py

@@ -30,6 +30,7 @@ import os
 import re
 from typing import Any, Callable, Dict, List, Mapping, Optional, Sequence, Tuple
 
+from ..gates import FeatureGate
 from ..quiet import quiet
 
 QUERY_CLASSES = ("fact", "code", "person", "recency")
@@ -50,8 +51,20 @@ FUSION_WEIGHTS_ENV = "LATTICEAI_FUSION_WEIGHTS"
 # 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"
+#: The one-switch form of the per-class table above, for the settings panel:
+#: "combine by rank instead of score", everywhere. It is applied as the *base*
+#: of the table, so the per-class ``LATTICEAI_FUSION_STRATEGY`` config — the
+#: more specific statement — still wins over it, and an install that touched
+#: neither is byte-identical to what it was.
+FUSION_RRF_ENV = "LATTICEAI_FUSION_RRF"
 FUSION_STRATEGIES = ("alpha", "rrf")
 DEFAULT_FUSION_STRATEGY: Dict[str, str] = dict.fromkeys(QUERY_CLASSES, "alpha")
+FUSION_RRF_GATE = FeatureGate(
+    FUSION_RRF_ENV,
+    default=False,
+    name="fusion_rrf",
+    detail="Search channels are combined by rank rather than by score.",
+)
 #: 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
@@ -195,8 +208,16 @@ def _env_strategy_overrides() -> Dict[str, str]:
 def fusion_strategy_table(
     overrides: Optional[Mapping[str, str]] = None,
 ) -> Dict[str, str]:
-    """Full per-class strategy table: defaults ← env override ← caller."""
+    """Full per-class table: defaults ← simple switch ← env override ← caller.
+
+    The simple switch (:data:`FUSION_RRF_GATE`, the settings panel's "combine by
+    rank") sits *under* the per-class env config on purpose: a person who wrote
+    ``{"code": "alpha"}`` said something specific, and a single global flag must
+    not overrule it.
+    """
     table = dict(DEFAULT_FUSION_STRATEGY)
+    if FUSION_RRF_GATE.enabled():
+        table = dict.fromkeys(QUERY_CLASSES, "rrf")
     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:
@@ -243,6 +264,14 @@ def rrf_fuse(
 # failure mode is dilution: an unbounded expansion turns a precise answer into
 # a tour of the graph.
 GRAPH_EXPANSION_ENV = "LATTICEAI_GRAPH_EXPANSION"
+#: Resolved when asked so the settings panel can move it without a restart; the
+#: env parsing is the same set of words the hand-written check used.
+GRAPH_EXPANSION_GATE = FeatureGate(
+    GRAPH_EXPANSION_ENV,
+    default=False,
+    name="graph_expansion",
+    detail="Memories one link away from a hit are offered as extra candidates.",
+)
 DEFAULT_EXPANSION_SEEDS = 3
 DEFAULT_EXPANSION_CAP = 5
 #: Expanded candidates inherit a damped share of their seed's score: they are
@@ -251,9 +280,8 @@ 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"}
+    """True when the expansion gate opts in (default: off)."""
+    return GRAPH_EXPANSION_GATE.enabled()
 
 
 def expand_with_neighbors(
@@ -348,10 +376,13 @@ __all__ = [
     "DEFAULT_FUSION_WEIGHTS",
     "DEFAULT_RRF_K",
     "EXPANSION_DECAY",
+    "FUSION_RRF_ENV",
+    "FUSION_RRF_GATE",
     "FUSION_STRATEGIES",
     "FUSION_STRATEGY_ENV",
     "FUSION_WEIGHTS_ENV",
     "GRAPH_EXPANSION_ENV",
+    "GRAPH_EXPANSION_GATE",
     "QUERY_CLASSES",
     "classify_query",
     "expand_with_neighbors",