ltcai 11.1.0 → 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.1.0 — Product Intelligence**.
+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.1.0)
+# 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/TRUST_MODEL.md

@@ -1,6 +1,6 @@
 # Lattice AI Trust Model
 
-Current release: **11.1.0 — Product Intelligence**.
+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.1.0 — Product Intelligence**.
+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.1.0 — Product Intelligence**.
+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.1.0"
+__version__ = "11.2.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"]

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

package/lattice_brain/graph/projection.py

@@ -52,16 +52,29 @@ class KnowledgeGraphProjectionMixin(_Core):
         END;
         """
 
-    # The temporal columns pass through *raw* (v11.1.0). ``type`` is COALESCEd
-    # because ``legacy_type`` carries the label a reader expects; validity is
-    # not a label — a COALESCE there would turn "still valid" (NULL) into a
-    # value, which is exactly the ``kgv2_edges`` trap noted in the 11.0.1
-    # review. NULL in, NULL out; the fallback to ``created_at`` belongs to the
-    # read predicate (``schema.TEMPORAL_PREDICATE_SQL``), not to the view.
+    # ``type`` is reconstructed from ``legacy_type`` when there is one, because
+    # that column carries the label a reader expects. The trap the 11.0.1
+    # review recorded — and which 11.2.0 fixes — is that ``edges_v2.legacy_type``
+    # is ``NOT NULL DEFAULT ''``: a natively-canonical edge is written with
+    # ``legacy_type=''`` so its identity is effectively (source, target, type),
+    # and ``COALESCE('', type)`` returns ``''`` because COALESCE only skips
+    # NULL. Every canonical edge therefore read back with an **empty type**.
+    # ``NULLIF(legacy_type, '')`` is the fix: empty means "no legacy label",
+    # which is precisely what the write side meant by it.
+    #
+    # The empty string stays the write-side sentinel on purpose. SQLite treats
+    # NULLs as distinct in a UNIQUE index, so moving to NULL would silently
+    # disable the (source, target, type, legacy_type) dedupe and let the same
+    # relation land twice.
+    #
+    # The temporal columns pass through *raw* (v11.1.0): validity is not a
+    # label, and a COALESCE there would turn "still valid" (NULL) into a value.
+    # NULL in, NULL out; the fallback to ``created_at`` belongs to the read
+    # predicate (``schema.TEMPORAL_PREDICATE_SQL``), not to the view.
     _V2_VIEWS_SQL = """
         CREATE VIEW IF NOT EXISTS kgv2_nodes AS
           SELECT id,
-                 COALESCE(legacy_type, type) AS type,
+                 COALESCE(NULLIF(legacy_type, ''), type) AS type,
                  label AS title,
                  summary,
                  attrs AS metadata_json,
@@ -70,7 +83,7 @@ class KnowledgeGraphProjectionMixin(_Core):
           FROM nodes_v2;
         CREATE VIEW IF NOT EXISTS kgv2_edges AS
           SELECT id, source AS from_node, target AS to_node,
-                 COALESCE(legacy_type, type) AS type,
+                 COALESCE(NULLIF(legacy_type, ''), type) AS type,
                  weight,
                  metadata AS metadata_json,
                  created_at,
@@ -156,6 +169,7 @@ class KnowledgeGraphProjectionMixin(_Core):
                 KGStoreV2(self.db_path).init_schema(conn=conn)
                 _exec_script(conn, self._V2_VIEWS_SQL)
                 self._backfill_v2_on(conn, force=stale)
+                self._normalize_v2_legacy_types(conn)
                 # version stamp commits together with the backfill — never stranded
                 conn.execute(
                     "INSERT OR REPLACE INTO kg_meta(key, value) VALUES ('projection_version', ?)",
@@ -177,6 +191,50 @@ class KnowledgeGraphProjectionMixin(_Core):
         except Exception as e:
             logging.warning("knowledge_graph: v2 schema init/backfill skipped: %s", e)
 
+    def _normalize_v2_legacy_types(self, conn: sqlite3.Connection) -> Dict[str, int]:
+        """Bring pre-11.2.0 rows onto the current ``legacy_type`` convention.
+
+        The convention is: ``legacy_type`` holds the *raw* label only when it
+        differs from the canonical type, and ``''`` (edges) / ``NULL`` (nodes)
+        otherwise. Rows written by older builds could carry the canonical value
+        in both columns, which is redundant and — because the dedupe key
+        includes ``legacy_type`` — splits one relation across two rows.
+
+        Idempotent by construction: a second run matches nothing. ``UPDATE OR
+        IGNORE`` is used because collapsing a redundant row can collide with
+        the canonical one that already exists; those survivors are counted and
+        reported rather than deleted, since the fixed view reads both
+        identically and deleting an edge is not a migration's business.
+        """
+        report = {"edges": 0, "nodes": 0, "collisions": 0}
+        try:
+            before = int(
+                conn.execute(
+                    "SELECT COUNT(*) FROM edges_v2 WHERE legacy_type = type"
+                ).fetchone()[0]
+                or 0
+            )
+            conn.execute(
+                "UPDATE OR IGNORE edges_v2 SET legacy_type='' WHERE legacy_type = type"
+            )
+            after = int(
+                conn.execute(
+                    "SELECT COUNT(*) FROM edges_v2 WHERE legacy_type = type"
+                ).fetchone()[0]
+                or 0
+            )
+            report["edges"] = before - after
+            report["collisions"] = after
+            cursor = conn.execute(
+                "UPDATE nodes_v2 SET legacy_type=NULL WHERE legacy_type = ''"
+            )
+            report["nodes"] = int(cursor.rowcount or 0)
+        except sqlite3.Error as exc:
+            # The projection is derived; a migration that cannot run leaves the
+            # data exactly as it was and the fixed view still reads it right.
+            logging.debug("knowledge_graph: legacy_type normalization skipped: %s", exc)
+        return report
+
     def _backup_before_v2_flip(self) -> Optional[str]:
         """Create one local SQLite backup before the v2 write-master flip."""
         if not self.db_path.exists() or self.db_path.stat().st_size == 0:

package/lattice_brain/graph/schema.py

@@ -134,6 +134,11 @@ class NodeType(str, Enum):
     # exists whether or not anyone could hear it. IMAGE has been first-class
     # since 3.6.0 for the same reason, and AUDIO now sits beside it.
     AUDIO = "AUDIO"  # 녹음 / 음성 메모
+    # v11.2.0 — a video is its own noun for the same reason a recording is:
+    # keyframes and subtitles are *derived* from it (IMAGE children, text
+    # chunks), and calling the thing they came from a DOCUMENT would make the
+    # source of a memory indistinguishable from one of its pieces.
+    VIDEO = "VIDEO"  # 영상 / 화면 녹화
 
     @classmethod
     def from_legacy(cls, label: str) -> "NodeType":
@@ -285,6 +290,10 @@ _LEGACY_NODE_MAP: Dict[str, NodeType] = {
     # v11.1.0 Multi-modal — recordings as a first-class noun.
     "audio": NodeType.AUDIO,
     "오디오": NodeType.AUDIO,
+    # v11.2.0 — videos likewise.
+    "video": NodeType.VIDEO,
+    "영상": NodeType.VIDEO,
+    "동영상": NodeType.VIDEO,
 }
 
 _LEGACY_EDGE_MAP: Dict[str, EdgeType] = {

package/lattice_brain/graph/store.py

@@ -241,6 +241,15 @@ class KnowledgeGraphStore(
                     CREATE INDEX IF NOT EXISTS idx_vector_embeddings_type ON vector_embeddings(item_type);
                     CREATE INDEX IF NOT EXISTS idx_vector_embeddings_source ON vector_embeddings(source_node);
                     CREATE INDEX IF NOT EXISTS idx_vector_embeddings_model ON vector_embeddings(embedding_model);
+                    -- v11.2.0: the ANN sidecar's freshness fingerprint is
+                    -- COUNT(*) + MAX(indexed_at) filtered by (embedding_model,
+                    -- embedding_dim), and it runs on *every* approximate
+                    -- search. Against the single-column model index that was a
+                    -- table scan of every row for the current model; this
+                    -- covering index answers both aggregates from the index
+                    -- alone. Additive and idempotent — no data is rewritten.
+                    CREATE INDEX IF NOT EXISTS idx_vector_embeddings_model_dim_indexed
+                      ON vector_embeddings(embedding_model, embedding_dim, indexed_at);
                     CREATE INDEX IF NOT EXISTS idx_vector_index_operations_requested ON vector_index_operations(requested_at);
                     CREATE INDEX IF NOT EXISTS idx_provenance_node ON ingestion_provenance(node_id);
                     CREATE INDEX IF NOT EXISTS idx_provenance_source_type ON ingestion_provenance(source_type);

package/lattice_brain/graph/vector_index/selector.py

@@ -11,13 +11,21 @@ exactly like "search is a bit worse today":
 
 Both resolve to the exact brute-force scan and carry a ``detail`` string
 naming the cause, which ``index_status()`` and the search result surface.
+
+The backend is a *choice*, not a switch, so it cannot ride a
+:class:`~lattice_brain.gates.FeatureGate` (which answers booleans). It gets the
+same shape of seam instead: :func:`bind_vector_index_resolver` installs a
+caller-supplied resolver that is consulted ahead of the environment, which is
+what lets the settings panel change the backend without a restart. With nothing
+bound — the default — the environment variable is still the whole control
+surface, exactly as before.
 """
 
 from __future__ import annotations
 
 import os
 from dataclasses import dataclass
-from typing import Any, Dict, Optional
+from typing import Any, Callable, Dict, Optional
 
 from .base import Similarity, VectorIndex
 from .brute_force import BRUTE_FORCE_BACKEND, BruteForceIndex
@@ -37,6 +45,23 @@ _BACKEND_LABELS = {
 _APPROX = {"brute": False, "quantized": True, "hnsw": True}
 _EXHAUSTIVE = {"brute": True, "quantized": True, "hnsw": False}
 
+#: App-layer resolver, consulted before the environment. ``None`` (the default)
+#: leaves this module reading exactly the env var it always read.
+_RESOLVER: Optional[Callable[[], Optional[str]]] = None
+
+
+def bind_vector_index_resolver(
+    resolver: Optional[Callable[[], Optional[str]]],
+) -> None:
+    """Delegate backend selection to a callable (``None`` hands it back to env).
+
+    A resolver that returns ``None`` also falls through to the environment, so
+    "the settings service has no opinion" and "there is no settings service"
+    reach the same answer instead of two.
+    """
+    global _RESOLVER
+    _RESOLVER = resolver
+
 
 @dataclass(frozen=True)
 class BackendSelection:
@@ -79,7 +104,11 @@ def _selection(name: str, *, requested: str, detail: Optional[str]) -> BackendSe
 
 def resolve_vector_index(requested: Optional[str] = None) -> BackendSelection:
     """Resolve the configured backend (never raises, always falls back safe)."""
-    raw = requested if requested is not None else os.getenv(VECTOR_INDEX_ENV, "")
+    raw = requested
+    if raw is None and _RESOLVER is not None:
+        raw = _RESOLVER()
+    if raw is None:
+        raw = os.getenv(VECTOR_INDEX_ENV, "")
     name = str(raw or "").strip().lower() or DEFAULT_VECTOR_INDEX
     if name not in VECTOR_INDEX_CHOICES:
         return _selection(
@@ -126,6 +155,7 @@ __all__ = [
     "VECTOR_INDEX_CHOICES",
     "VECTOR_INDEX_ENV",
     "BackendSelection",
+    "bind_vector_index_resolver",
     "build_index",
     "resolve_vector_index",
 ]