ltcai 10.2.0 → 10.4.0

package/README.md

@@ -11,7 +11,7 @@
 [![CI Status](https://github.com/TaeSooPark-PTS/LatticeAI/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/TaeSooPark-PTS/LatticeAI/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
-![v10.2.0 Living Brain walkthrough](output/release/v10.2.0/gifs/v10.2.0-living-brain-walkthrough.gif)
+![v10.4.0 Living Brain walkthrough](output/release/v10.4.0/gifs/v10.4.0-living-brain-walkthrough.gif)
 
 Chat, files, folders, notes, and web pages all flow into one durable knowledge
 graph on your computer. Any model — local MLX or cloud — can speak with that
@@ -24,9 +24,9 @@ memory. Nothing leaves your machine without explicit consent.
 
 | | |
 | --- | --- |
-| **Chat with a Brain that remembers** — every conversation grows durable, source-linked memory ![Brain Chat](output/release/v10.2.0/screenshots/04-brain-chat-home.png) | **See how knowledge connects** — a real relationship graph, not a file list ![Memory Graph](output/release/v10.2.0/screenshots/05-memory-graph.png) |
-| **Capture anything** — files, whole folders, notes, screenshots, web pages ![Capture](output/release/v10.2.0/screenshots/06-capture.png) | **Automate with review** — agent changes become proposals you approve first ![Review Center](output/release/v10.2.0/screenshots/12-review-center.png) |
-| **Pick a model in one click** — recommended local models for your hardware ![Recommended Models](output/release/v10.2.0/screenshots/02-recommended-models.png) | **Stay in control** — audit, roles, retention in a separate admin surface ![Admin Console](output/release/v10.2.0/screenshots/10-admin-console.png) |
+| **Chat with a Brain that remembers** — every conversation grows durable, source-linked memory ![Brain Chat](output/release/v10.4.0/screenshots/04-brain-chat-home.png) | **See how knowledge connects** — a real relationship graph, not a file list ![Memory Graph](output/release/v10.4.0/screenshots/05-memory-graph.png) |
+| **Capture anything** — files, whole folders, notes, screenshots, web pages ![Capture](output/release/v10.4.0/screenshots/06-capture.png) | **Automate with review** — agent changes become proposals you approve first ![Review Center](output/release/v10.4.0/screenshots/12-review-center.png) |
+| **Pick a model in one click** — recommended local models for your hardware ![Recommended Models](output/release/v10.4.0/screenshots/02-recommended-models.png) | **Stay in control** — audit, roles, retention in a separate admin surface ![Admin Console](output/release/v10.4.0/screenshots/10-admin-console.png) |
 
 ## Why Lattice AI
 
@@ -57,53 +57,47 @@ First-run flow — wake the Brain, pick the owner, load a recommended model:
 
 | | | |
 | --- | --- | --- |
-| ![Login](output/release/v10.2.0/screenshots/01-login.png) | ![Model install](output/release/v10.2.0/screenshots/03-install-load-progress.png) | ![Model library](output/release/v10.2.0/screenshots/07-model-library.png) |
+| ![Login](output/release/v10.4.0/screenshots/01-login.png) | ![Model install](output/release/v10.4.0/screenshots/03-install-load-progress.png) | ![Model library](output/release/v10.4.0/screenshots/07-model-library.png) |
 
 Screenshot index and capture notes:
-[output/release/v10.2.0/SCREENSHOT_INDEX.md](output/release/v10.2.0/SCREENSHOT_INDEX.md)
+[output/release/v10.4.0/SCREENSHOT_INDEX.md](output/release/v10.4.0/SCREENSHOT_INDEX.md)
 
 ## Current Release
 
-The current release is **10.2.0 — Load-Bearing Fixes**:
-
-A full code review of 10.1.1 scored the codebase 71/100 and found two things
-that were true but invisible. This release is that review's response.
-
-- **A database connection leak that hid behind garbage collection.**
-  `with sqlite3.connect(...)` commits but never closes, and 70+ call sites
-  relied on it. Nothing showed until something held a stack frame alive — a
-  profiler, a logged traceback, a coverage tracer — and then descriptors ran
-  out. Every one of those sites now closes.
-- **Coverage is measurable for the first time: 71%.** It could not be run
-  before, because running it *was* the thing that exhausted descriptors. There
-  is now a floor in CI so it cannot silently fall.
-- **"Sensitive memories are never sent" is finally true.** The filter was real,
-  correct, and wired — but nothing in the product could mark a memory, and the
-  blocked-type list was empty, so it could never fire. You can now mark any
-  memory from the boundary panel, files under `.ssh`/`.aws`/`.env` and friends
-  are flagged automatically at ingestion, and credential-shaped node types are
-  blocked outright.
-- **Knowledge that leaves is now redacted and recorded.** Secret-shaped text is
-  stripped from the outbound payload, and every send — and every refusal —
-  writes an audit entry naming what went, how much, and where to.
-- **112 silent `except: pass` handlers now say something.** Behaviour is
-  unchanged; each records the failure at debug level, so a genuine bug in an
-  optional path is no longer indistinguishable from the optional thing being
-  absent.
-- **The lint net was widened to the bug classes that actually bit** — loop
-  variable capture, truncating `zip`, silent handlers — and mypy now runs on
-  the trust-critical modules. CI gained macOS and Python 3.14, so the machine
-  this is developed on and the platform it ships a `.dmg` for are both tested.
+The current release is **10.4.0 — Named Ground**:
+
+10.3.0 wrote down what was not measured. 10.4.0 emptied that list — and the
+things that made the list long turned out not to be typing problems.
+
+- **The type backlog went from 1,407 errors across 77 modules to zero across
+  274.** Two root causes accounted for 954 of them, and both were readability
+  problems: a computed `__all__` that made every star-imported name invisible
+  to a checker, and an eleven-mixin contract that existed but was written down
+  nowhere. Both are now explicit, and both are guarded by tests.
+- **The composition root is no longer one function.** `app_factory._build` went
+  from 1,318 lines to 26, split into ten ordered phases sharing a typed
+  `RuntimeContext`. The phase order is a contract with a test, not a comment —
+  and reading a value before its phase has run fails by name.
+- **Four real defects surfaced on the way**, including one that meant
+  `python -m latticeai.server_app` had never worked: `main` was a local inside
+  the old closure and was never on the export list.
+- **The surface-parity matrix has no ◐ left.** VS Code gained folder capture,
+  artifact cards with their repair/validation flags, and a hardware-derived
+  model recommendation; Telegram gained the same artifact card. All four were
+  rendering gaps — the sidecar was already reporting the data.
+- **Coverage moved honestly, not to target.** Frontend 28.5% → 32.3% (208 → 337
+  tests), Python 71.6% → 71.8% (1,896 → 1,956). Frontend 70% is still roughly
+  2,200 statements away, and this release does not claim otherwise.
 
 Release notes: [RELEASE.md](RELEASE.md) · Full history: [docs/CHANGELOG.md](docs/CHANGELOG.md)
 
-Expected artifacts for 10.2.0 release must use exact filenames:
+Expected artifacts for 10.4.0 release must use exact filenames:
 
-- `dist/ltcai-10.2.0-py3-none-any.whl`
-- `dist/ltcai-10.2.0.tar.gz`
-- `ltcai-10.2.0.tgz`
-- `dist/ltcai-10.2.0.vsix`
-- `src-tauri/target/release/bundle/dmg/Lattice AI_10.2.0_aarch64.dmg`
+- `dist/ltcai-10.4.0-py3-none-any.whl`
+- `dist/ltcai-10.4.0.tar.gz`
+- `ltcai-10.4.0.tgz`
+- `dist/ltcai-10.4.0.vsix`
+- `src-tauri/target/release/bundle/dmg/Lattice AI_10.4.0_aarch64.dmg`
 
 Do not use wildcard artifact uploads. Package registry publishing remains owner-run.
 
@@ -123,7 +117,7 @@ See [ARCHITECTURE.md](ARCHITECTURE.md) for details and
 
 - External package registries are owner-published and can lag behind GitHub.
 - PostgreSQL/pgvector is optional scale/migration tooling. SQLite remains the
-  live local Brain store in 10.2.0.
+  live local Brain store in 10.3.0.
 - Docker, model downloads, cloud model calls, Telegram, Brain Network, and
   update checks require explicit user action.
 - Conversation does not fabricate answers when no model is loaded. Agent and
@@ -132,12 +126,14 @@ See [ARCHITECTURE.md](ARCHITECTURE.md) for details and
   model success.
 - Some backend-generated messages (for example the Postgres DSN notice) are
   produced server-side in English and are shown as-is; server-side i18n is not
-  part of 10.2.0.
+  part of 10.3.0.
 
 ## Release History
 
 | Version | Theme |
 | --- | --- |
+| 10.4.0 | Named Ground |
+| 10.3.0 | Measured Ground |
 | 10.2.0 | Load-Bearing Fixes |
 | 10.1.1 | Reachable Boundary |
 | 10.1.0 | Hybrid Brain |

package/docs/CHANGELOG.md

@@ -4,6 +4,131 @@ The top entry is either the current unreleased main-branch work or the current
 release line. Older entries are historical and may describe behavior as it
 existed at that release.
 
+## [10.4.0] - 2026-08-02
+
+### Changed
+- **`app_factory._build` is decomposed.** 1,318 lines → 26. The assembly now
+  lives in `latticeai/runtime/build_phases.py` as ten ordered phases sharing a
+  typed `latticeai/runtime/runtime_context.py::RuntimeContext`:
+  `platform → config → identity → brain → domain → web → services →
+  foundation_routes → platform_features → interaction`.
+  The single closure worked because closures resolve free variables at call
+  time; several sections depend on names bound far below them. The
+  RuntimeContext preserves that late binding while naming the shared state.
+  `tests/unit/test_runtime_context.py` fixes the phase order, which phase
+  produces which attribute, and that reading one early fails by name.
+- **mypy covers the whole tree: 274 of 274 modules, 0 errors** (was 193 of 270
+  with 1,407 outstanding). `pyproject.toml`'s `[tool.mypy] files` is no longer
+  a curated subset.
+- `lattice_brain/graph/_kg_common.py`'s `__all__` is a literal instead of a
+  comprehension over `globals()`. The computed form was invisible to a type
+  checker, so twelve modules resolved no names behind
+  `from ._kg_common import *` (~750 false `name-defined` errors).
+  `tests/unit/test_kg_common_exports.py` keeps the literal honest.
+- The star import of `._kg_fsutil` inside `_kg_common` is now an explicit list
+  for the same reason.
+- JSON-shaped payloads in `services/model_runtime.py`, `model_engines.py`,
+  `model_catalog.py`, `api/setup.py` and `api/models.py` are typed
+  `Dict[str, Any]` rather than `Dict[str, object]`, which forced a cast at
+  every nested access without catching anything.
+- Optional dependencies (`AsyncOpenAI`, `mx`, `vlm_load`, `lm_load`,
+  `pyautogui`) are aliased on import and re-exported as `Any`, so "installed"
+  and "absent" have one declared type.
+
+### Added
+- `lattice_brain/graph/_kg_contract.py` — the 23-member surface the eleven
+  graph mixins share, written down for the first time. Typing-only: `_Core` is
+  `object` at runtime, so `KnowledgeGraphStore`'s MRO is unchanged.
+  `tests/unit/test_kg_contract.py` asserts both the contract and that it never
+  becomes a real base class.
+- `AppContext.require(field)` — binds a dependency a router cannot run without,
+  so an absent one names itself at router construction instead of surfacing as
+  `'NoneType' object is not callable` inside a request handler.
+- VS Code `ltcai.captureFolder` — folder ingestion through the same
+  `/api/ingestion/folder` endpoint and the same local-read approval dance the
+  web Capture view uses.
+- VS Code `ltcai.showArtifacts` — `artifacts[]` rendered as cards with the
+  server's repair and validation flags, so a deterministically repaired
+  scaffold no longer looks identical to clean model output.
+- VS Code model picker now shows the hardware-derived recommendation from
+  `GET /setup/scan`, with the server's own reasoning. No scan, no banner.
+- Telegram sends the same `artifacts[]` card summary before the files.
+- Frontend tests for four previously untested modules with real logic:
+  `routes.ts`, `store/appStore.ts`, `api/base.ts` error translation, and
+  `pages/brain/graphExplorer.ts`.
+
+### Fixed
+- **`python -m latticeai.server_app` raised `AttributeError`.** `main` was a
+  local inside the old `_build` closure and was never on the export allowlist,
+  so `get_shared_runtime().main()` could never resolve it. `main()` now serves
+  the shared runtime directly and needs no export.
+- `core/workspace_os.py`: four lines duplicated after a `return` in
+  `remove_member` — dead since the merge that introduced them.
+- `models/router.py`: a `str` shadowed a `dict` in the custom cloud-model loop,
+  so those entries built their ids from the wrong variable.
+- `lattice_brain/context.py`: an unconfigured retrieval seam was called
+  unguarded and died as a `TypeError` inside failure isolation instead of
+  naming itself.
+- `runtime/review_wiring.py` declared its injected `HTTPException` as
+  `type[Exception]`, which does not accept `(status_code=, detail=)`.
+- `api/security_dashboard.py`: a defensive `isinstance(rows, list)` re-check
+  that every branch above already guaranteed.
+
+### Documentation
+- `docs/MYPY_BACKLOG.md` is now the record of how the boundary closed, not a
+  list of what is left — including the conventions the sweep settled on.
+- `docs/SURFACE_PARITY.md`: no ◐ remains in the matrix. A stale v9.9.6 note
+  claiming the live step timeline was web-only is corrected (v9.9.7's
+  `runAgentLive` provides it).
+
+## [10.3.0] - 2026-07-29
+
+### Fixed
+- **Frontend coverage was not being measured.** Vitest reports only files a
+  test imports unless `all: true`; untested modules left the denominator
+  instead of counting against it. Reported 54%, actual **28.5%**.
+- **Python coverage was over-reported.** `omit = ["*/tests/*"]` does not match
+  the repo-relative `tests/...` paths coverage records, so the suite counted
+  itself. Reported 80%, actual **71.6%**.
+- `lattice_brain/runtime/hooks.py` referenced `self._path` (does not exist)
+  inside the handler for an unreadable registry, turning a recoverable failure
+  into `AttributeError`.
+- `lattice_brain/graph/_kg_fsutil.py` used `Iterable` in an annotation without
+  importing it.
+- `lattice_brain/runtime/agent_runtime.py` could call `.get` on `None`.
+- `pages/Library.tsx` printed the raw registry coordinate
+  (`mlx-community/gemma-4-…`) when a catalog entry had no display name; it now
+  falls through `humanizeModelId` like every other model surface.
+
+### Added
+- `latticeai/runtime/history_writer.py` — `save_to_history` extracted from the
+  `app_factory._build` closure with its ordering contract documented, plus 14
+  tests (`tests/unit/test_history_writer.py`).
+- `frontend/src/test/renderPage.tsx` — a page-level harness that stubs the
+  whole `latticeApi` surface, making error states, empty states and both
+  languages reachable in unit tests.
+- First unit tests for every page: `System` (11), `Library` (7), `Capture` (6),
+  `Act` (8), `Brain` (8). Frontend suite 154 → 208 tests.
+- Python tests for boundaries that had none: Telegram allowlist (26),
+  `run_command` containment (34), audit log and sensitivity report (22),
+  model-load consent gates (14), connection lifecycle guards. 1,786 → 1,896.
+- `docs/MYPY_BACKLOG.md` — the 77 modules still outside type checking with
+  per-module error counts, smallest first.
+- ARCHITECTURE.md "Verification Surface" diagram: which figures gate CI and
+  which are only reported.
+
+### Changed
+- mypy adopted set: 13 → **193 of 270** modules.
+- `vitest.config.ts` gains a coverage block with `all: true`.
+- `npm run test:frontend:coverage` added.
+
+### Known
+- `app_factory._build` remains ~1,300 lines; only the history writer was
+  extracted this release.
+- Frontend coverage (28.5%) is reported but not gated — flooring it at today's
+  figure would freeze it there.
+- 77 modules remain outside mypy; see the backlog.
+
 ## [10.2.0] - 2026-07-29
 
 Response to a full code review of 10.1.1 (71/100). All twelve findings.

package/docs/COMMUNITY_AND_PLUGINS.md

@@ -1,6 +1,6 @@
 # Community And Plugins
 
-Current release: **10.2.0 — Load-Bearing Fixes**.
+Current release: **10.4.0 — Named Ground**.
 
 LatticeAI defines the path from a strong local-first framework (8.4.0
 action-aware baseline, 8.5.0 registry+DI hardening, 8.6.0 capture/navigation

package/docs/DEVELOPMENT.md

@@ -3,7 +3,7 @@
 > **Status: canonical** — current contributor guidance, kept in sync with the
 > current release.
 
-Current release: **10.2.0 — Load-Bearing Fixes**.
+Current release: **10.4.0 — Named Ground**.
 
 This document is for contributors working on the local-first Digital Brain
 codebase. Product positioning and quick start stay in `README.md`; release

package/docs/MYPY_BACKLOG.md

@@ -0,0 +1,65 @@
+# mypy backlog
+
+> **Status: reference**
+> 10.2.0: 13 modules checked. 10.3.0: 193 of 270, with the remaining 77 listed
+> here by error count. **10.4.0: 274 of 274 — the backlog is empty.**
+
+`[tool.mypy] files` in `pyproject.toml` now lists **every** module in
+`lattice_brain/` and `latticeai/`. There is no "adopted set" any more; adding a
+module to the tree adds it to the checked set, and CI fails if it does not
+type-check.
+
+This file stays as the record of how the boundary closed, because two of the
+1,407 errors 10.3.0 measured turned out to be worth more than the annotations.
+
+## Two root causes were 68% of the backlog
+
+**`_kg_common.__all__` was computed** (`[name for name in globals() if not
+name.startswith("__")]`). Correct at runtime, opaque to a checker: mypy could
+not resolve a single name behind `from ._kg_common import *`, so twelve graph
+modules reported **~750 false `name-defined` errors** and stayed unchecked.
+Freezing the list to a literal fixed all of them.
+`tests/unit/test_kg_common_exports.py` asserts the literal still equals what
+the expression would produce, so it cannot drift.
+
+**The eleven graph mixins had an unwritten contract.** `ingest` calls
+`_upsert_node` from `write_master`, which calls `_v2_project_node` from
+`projection`, and everything calls `_connect` — 229 `attr-defined` errors,
+because from a checker's position each mixin is a bare class calling methods it
+does not have. `lattice_brain/graph/_kg_contract.py` writes that contract down:
+23 declared members, typing-only (`_Core` is `object` at runtime, so the MRO is
+unchanged), verified by `tests/unit/test_kg_contract.py`.
+
+Neither was a typing problem. Both were *readability* problems that a reader
+had to solve by grepping eleven files.
+
+## Real defects the remaining work surfaced
+
+| defect | module | why it mattered |
+| --- | --- | --- |
+| four lines duplicated after a `return` | `core/workspace_os.py` | dead since the merge that introduced it; `remove_member` looked like it did its work twice |
+| `main` was never exported | `app_factory.py` | `python -m latticeai.server_app` raised `AttributeError` — the module entrypoint did not run |
+| `str` shadowed a `dict` in a loop | `models/router.py` | the custom-cloud-model branch built ids from the wrong variable |
+| `Optional` seam called unguarded | `lattice_brain/context.py` | an unconfigured retrieval port raised `TypeError` inside failure isolation instead of naming itself |
+
+(10.3.0 found three more the same way: `self._path` inside an error handler,
+`Iterable` used without importing it, and `.get` on a possible `None`.)
+
+## Conventions the sweep settled on
+
+* **JSON-shaped payloads are `Dict[str, Any]`, not `Dict[str, object]`.**
+  `object` forced a cast at every nested access without catching anything;
+  the value really is arbitrary JSON.
+* **Optional dependencies are aliased, then re-exported as `Any`**
+  (`AsyncOpenAI`, `mx`, `vlm_load`, `pyautogui`), so "installed" and "absent"
+  have the same declared type and call sites keep their historical name.
+* **Async generators in Protocols are declared with `def`, not `async def`.**
+  `async def … -> AsyncIterator[T]` says "a coroutine resolving to an
+  iterator", which no implementation does.
+* **A router dependency it cannot run without is bound through
+  `AppContext.require("name")`** — an absent dependency names itself at router
+  construction instead of surfacing as `'NoneType' object is not callable`
+  inside a request handler.
+* **A defensive `isinstance` check on a parameter means the annotation is
+  wrong.** Widen the parameter (`Any`, `Optional[str]`) rather than deleting
+  the guard: the guard is what the callers actually need.

package/docs/ONBOARDING.md

@@ -1,6 +1,6 @@
 # Lattice AI Onboarding
 
-Current release: **10.2.0 — Load-Bearing Fixes**.
+Current release: **10.4.0 — Named Ground**.
 
 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 (v10.2.0)
+# Lattice AI — Operations Guide (v10.4.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/SURFACE_PARITY.md

@@ -2,7 +2,8 @@
 
 > **Status: reference**
 > 도입: v9.9.4 (2026-07-25, 리뷰 Wave 1.4 "표면 패리티 체크리스트").
-> 갱신: v9.9.7 — 표에 남아 있던 ✖ 갭을 **전부** 해소. Browser 확장도 캡처 전용 경계를 넘어 회상/승인 가시성을 갖췄다.
+> 갱신: v9.9.7 — 표에 남아 있던 ✖ 갭을 **전부** 해소.
+> 갱신: **v10.4.0 — 남아 있던 ◐(부분 제공)를 전부 해소.** 표에 ◐ 는 더 이상 없다.
 > 목적: 각 표면(서피스)이 Brain 계약의 어디까지를 제공하는지 **정직하게** 기록한다.
 > "앱마다 다른 Lattice"를 방지하는 기준표이며, 기능을 과장하지 않는다.
 
@@ -22,9 +23,9 @@
 
 | 루프 순간 | Web `/app` | Desktop | VS Code | Browser | Telegram |
 | --- | --- | --- | --- | --- | --- |
-| 첫 저장 (Capture) | ✅ DnD·폴더·웹 수집, 품질 경고 | ✅ (웹과 동일) | ◐ `sendToLattice` 선택 영역 전송 | ✅ 페이지 캡처 (단일 목적) | ◐ 메시지 수집 |
+| 첫 저장 (Capture) | ✅ DnD·폴더·웹 수집, 품질 경고 | ✅ (웹과 동일) | ✅ `sendToLattice` 파일/선택 + `captureFolder` 폴더 수집 (v10.4.0) | ✅ 페이지 캡처 (단일 목적) | ✅ 메시지 + 문서/사진 업로드 수집 |
 | 첫 회상 (Recall) | ✅ 하이브리드 검색 + grounding 배지 + 출처→청크 | ✅ (동일) | ✅ `askCurrentFile`/`askBrain` — 동일 `/chat` grounding 배지 | ✅ 팝업 질문 + 동일 grounding 배지 (v9.9.7) | ✅ 답변 + grounding 배지 (v9.9.7) |
-| 첫 산출물 (Artifact) | ✅ artifacts[] 카드·미리보기·Brain 기억 칩 | ✅ (동일) | ◐ `createFile` + `runAgent`/`runAgentLive` 스텝·파일 요약, 카드 UI 없음 | — (의도: 브라우저에서 파일 쓰기 없음) | ◐ 파일 전송만 |
+| 첫 산출물 (Artifact) | ✅ artifacts[] 카드·미리보기·Brain 기억 칩 | ✅ (동일) | ✅ `createFile` + `showArtifacts` 카드(보정/검증 플래그 포함, v10.4.0) | — (의도: 브라우저에서 파일 쓰기 없음) | ✅ 파일 + artifacts[] 카드 요약 (v10.4.0) |
 | 첫 보호 (Approval) | ✅ 승인 카드 + TTL 카운트다운 + 재시작 생존 | ✅ (동일) | ✅ List/Approve/Reject 커맨드 + 토큰 캐시 | ✅ 대기 건수 표시 (승인은 웹에서, v9.9.7) | ✅ 인라인 Done/Cancel + run_id/token 재개 |
 
 ## 기능 상세 × 표면
@@ -42,14 +43,14 @@
 | Watch 상태 신호 (v9.9.4) | ✅ 홈 카드 | ✅ | — | — | — |
 | Review Center (제안 승인/거절) | ✅ | ✅ | ✅ `ltcai.reviewCenter` (409 충돌 정직 보고) | — (의도: 승인은 웹/에디터/봇에서) | ✅ `/review` + 인라인 승인/거절 (v9.9.7) |
 | 데모 코퍼스 First Value Loop | ✅ | ✅ | — | — | — |
-| 모델 로드/추천 | ✅ | ✅ | ◐ `loadModel` | — | — |
+| 모델 로드/추천 | ✅ | ✅ | ✅ `loadModel` + 하드웨어 기반 추천·근거 (v10.4.0) | — (의도) | — (의도) |
 | 코드 편집 보조 (edit/explain/refactor/tests) | — | — | ✅ | — | — |
 
 ## 규칙
 
 1. **API 계약이 기준이다.** 모든 표면은 동일한 sidecar API를 소비한다. 표면별 전용 API를 만들지 않는다.
 2. **◐/✖ 는 문서화된 상태로만 존재한다.** 새 기능을 Web에 추가할 때 이 표를 갱신하고, 다른 표면에 제공하지 않을 경우 "—(의도)" 인지 "✖(갭)" 인지 명시한다.
-3. **✖ 갭은 릴리스 노트의 Honest Limitations 후보다.** v9.9.7 기준 표에 남은 ✖는 **없다**.
+3. **✖ 갭은 릴리스 노트의 Honest Limitations 후보다.** v9.9.7 이후 표에 남은 ✖는 **없고**, v10.4.0 이후 ◐ 도 **없다**.
    - 남은 "—"는 전부 **설계 경계**이며, 각 항목에 이유를 함께 적는다. 예: 브라우저 확장은 파일을 쓰지 않으므로 산출물 생성이 없고, 승인 *결정*은 서명된 토큰이 필요한 흐름이라 대기 건수만 보여 주고 승인은 웹/에디터/봇에서 한다.
    - 경계를 새로 만들 때는 "왜 제공하지 않는가"를 이 문서에 남긴다. 이유 없는 "—"는 갭이지 경계가 아니다.
 4. 릴리스마다 이 표를 검토한다 (release checklist의 docs 단계).
@@ -63,7 +64,7 @@
 
 - **회상 배지**: `askCurrentFile` / `askBrain`은 웹과 동일한 `POST /chat` 응답의 `grounding` 판정을 그대로 읽는다. 판정이 없으면 "근거 있음"으로 승격하지 않고 `unknown`으로 보고한다 (`vscode-extension/surface.ts::groundingBadge`).
 - **Review Center**: `ltcai.reviewCenter`는 웹과 같은 `/api/proposals` 표면을 쓴다. 승인은 검토한 내용 그대로 적용하고, 409(스테이징 이후 파일 변경)는 "아무것도 쓰지 않았다"고 정직하게 알린다.
-- **스텝 요약**: `ltcai.runAgent`는 실행 후 `steps`/`created_files`/`explanation`을 출력 채널에 요약한다. 라이브 SSE 타임라인은 아직 웹 전용이다 (◐).
+- **스텝 요약**: `ltcai.runAgent`는 실행 후 `steps`/`created_files`/`explanation`을 출력 채널에 요약한다. (라이브 SSE 타임라인은 v9.9.7의 `ltcai.runAgentLive`가 같은 `agent_step` 프레임으로 제공한다 — 이 메모는 v9.9.6 시점 기준이었다.)
 - 파싱 계약은 `tests/vscode-extension.test.cjs`가 sidecar 페이로드 모양 그대로 검증한다.
 
 ## v9.9.7 — 남은 갭을 닫은 방법
@@ -81,3 +82,29 @@
 - **Browser 확장**: 캡처 전용 경계를 넘어 `/chat` 질문과 `agent/approvals` 대기
   건수를 보여 준다. **판정을 로컬에서 계산하지 않는다** — 판정이 없으면
   "근거 확인 불가"이며 절대 "근거 있음"으로 승격하지 않는다.
+
+## v10.4.0 — 마지막 ◐ 셋을 닫은 방법
+
+세 갭 모두 **계약의 문제가 아니라 렌더링의 문제**였다. 사이드카는 이미 필요한
+데이터를 내고 있었고, 에디터/봇이 그것을 버리고 있었다.
+
+- **VS Code 폴더 수집** (`ltcai.captureFolder`): 웹 Capture 와 **같은**
+  `POST /api/ingestion/folder` 를 쓴다. 로컬 디스크를 읽으므로 승인 절차도
+  동일하다 — 토큰 없는 첫 호출은 `permission_required` 이고, 확장은 그것을
+  그대로 보여 준다(조용히 재시도하지 않는다). 백그라운드 job 으로 큐잉되며
+  진행 상황은 웹에서 본다.
+- **VS Code 산출물 카드** (`ltcai.showArtifacts`): `/agent` 응답의
+  `artifacts[]` 를 그대로 읽는다. 결정적으로 **보정된(repaired) 스캐폴드와
+  깨끗한 모델 출력이 구분된다** — 이전에는 평평한 경로 목록이라 둘이 같아
+  보였다. 서버의 `valid=false` 판정을 확장이 성공으로 승격하지 않는다.
+  구형 사이드카(`created_files` 만 있는 응답)는 "세부 정보 없음"이라고
+  정직하게 말한다.
+- **VS Code 모델 추천**: `GET /setup/scan` 의 `zero_config.recommend` 를
+  읽어 **이 기기에 왜 이 모델인지**를 근거와 함께 보여 준다. 스캔이 없으면
+  배너도 없다 — 이유를 지어내지 않는다.
+- **Telegram 산출물 카드**: 같은 `artifacts[]` 플래그를 파일 전송 직전에
+  요약한다. 8개까지 나열하고 나머지는 `… +N` 으로 정직하게 줄인다.
+
+계약 테스트: `tests/vscode-extension.test.cjs` (19), `tests/unit/test_telegram_security.py`.
+전부 사이드카 페이로드 모양 그대로 검증하며, 확장/봇이 서버 판정을 재계산하지
+않는지도 함께 고정한다.

package/docs/TRUST_MODEL.md

@@ -1,6 +1,6 @@
 # Lattice AI Trust Model
 
-Current release: **10.2.0 — Load-Bearing Fixes**.
+Current release: **10.4.0 — Named Ground**.
 
 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: **10.2.0 — Load-Bearing Fixes**.
+Current release: **10.4.0 — Named Ground**.
 
 **Lattice AI is a local-first Digital Brain that keeps your knowledge durable
 across any AI model.**

package/docs/kg-schema.md

@@ -1,6 +1,6 @@
 # Knowledge Graph Schema
 
-Current release: **10.2.0 — Load-Bearing Fixes**.
+Current release: **10.4.0 — Named Ground**.
 
 명세 출처: `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__ = "10.2.0"
+__version__ = "10.4.0"
 
 __all__ = [
     "AgentRuntime",

package/lattice_brain/context.py

@@ -24,14 +24,27 @@ def approx_tokens(text: str) -> int:
     return max(0, (len(text or "") + 3) // 4)
 
 
-def _call_context_seam(callback: Callable[..., Any], query: str, **context: Any) -> Any:
+class _SeamUnavailable(RuntimeError):
+    """Raised when a context seam is called but was never configured."""
+
+
+def _call_context_seam(
+    callback: Optional[Callable[..., Any]], query: str, **context: Any
+) -> Any:
     """Pass identity/scope only when a legacy seam declares support for it.
 
     Signature inspection preserves old one-argument adapters without catching
     a callback's own ``TypeError`` and retrying it with less restrictive scope.
     If a callable cannot be inspected, the secure behavior is to pass every
     context field and let the caller's failure isolation omit that section.
+
+    ``callback`` is Optional because the seams themselves are: an assembler
+    built without a hybrid-search port simply has no knowledge section. The
+    section builders already run inside failure isolation, so an unconfigured
+    seam degrades to "section omitted" rather than crashing the turn.
     """
+    if callback is None:
+        raise _SeamUnavailable("seam is not configured")
     try:
         parameters = inspect.signature(callback).parameters
     except (TypeError, ValueError):
@@ -47,8 +60,12 @@ def _call_context_seam(callback: Callable[..., Any], query: str, **context: Any)
     return callback(query, **supported)
 
 
-def _call_keyword_seam(callback: Callable[..., Any], **context: Any) -> Any:
+def _call_keyword_seam(
+    callback: Optional[Callable[..., Any]], **context: Any
+) -> Any:
     """Invoke a keyword-only seam while preserving legacy narrow signatures."""
+    if callback is None:
+        raise _SeamUnavailable("seam is not configured")
     try:
         parameters = inspect.signature(callback).parameters
     except (TypeError, ValueError):
@@ -177,7 +194,10 @@ class ContextAssembler:
     # ── section builders (each failure-isolated and honest) ───────────────
     def _memories_section(self, query, user_email, workspace_id, limit) -> ContextSection:
         try:
-            recall = self._memory_recall(query, user_email=user_email, workspace_id=workspace_id, limit=limit)
+            recall_seam = self._memory_recall
+            if recall_seam is None:
+                raise _SeamUnavailable("memory_recall is not configured")
+            recall = recall_seam(query, user_email=user_email, workspace_id=workspace_id, limit=limit)
             results = [r for r in recall.get("results", []) if r.get("source") == "workspace"][:limit]
         except Exception as exc:
             logging.debug("context: memory recall failed: %s", exc)