ltcai 9.5.0 → 9.7.0

package/README.md

@@ -1,9 +1,17 @@
 # Lattice AI
 
-**Lattice AI 9.5.0 is the local-first Digital Brain platform. The Command Center puts everything one keystroke away: a Cmd+K palette that searches knowledge, past conversations, automations, and app pages in one query, and a daily briefing that condenses recent knowledge, automation state, pending reviews, Brain health, and suggested next steps into one glance with one-click quick actions.**
+**Lattice AI 9.6.0 is the local-first Digital Brain platform. The Trusted Agent Loop makes autonomous work transparent and git-like: the reasoning loop reports every model call, format repair, and tool outcome; a deterministic evaluation harness gates every release on weak-model robustness; and change governance is proposal-first — creating new files is frictionless while edits and deletions of existing content become reviewable proposals you approve or reject before anything changes.**
 
 **Lattice AI는 모델이 바뀌어도 내 지식과 맥락을 보존하는 로컬 우선 AI 브레인입니다.**
 
+> The 9.6.0 release engineers trust into the agent loop: a structured
+> LoopTrace makes every run observable (llm calls, parse recoveries, format
+> repairs, corrections, tool outcomes — returned as `loop` in the agent API),
+> weak-model tolerance gains python-literal repair and escalating format
+> corrections, a deterministic agent evaluation harness gates CI, and a
+> central change governor stages edits/deletions of existing files as review
+> proposals (`/api/proposals`) applied exactly as reviewed — while new-file
+> creation now runs without approval friction.
 > The 9.5.0 release adds the Command Center: a deterministic, local
 > `/api/command` surface serving a daily briefing (recent knowledge,
 > conversation activity, automation state, pending reviews, health snapshot,
@@ -108,11 +116,11 @@ You need Lattice AI when:
 The screenshots below are the latest checked-in visual evidence captures. They
 keep the first-run Brain flow, memory graph, source capture, model library,
 system view, admin console, and review center visible as release gates while
-9.5.0 puts the whole Brain one keystroke away: the Cmd+K Command Palette
-searches knowledge, conversations, automations, and pages in one query, and
-Today's Briefing condenses the Brain's state into one glance with one-click
-next steps. The captures below are the checked-in 9.5.0 visual release
-evidence for that product flow.
+9.6.0 makes autonomous work trustworthy: agents create new things freely,
+but every change to existing content becomes a reviewable proposal with a
+diff, and the reasoning loop itself is observable and regression-gated. The
+captures below are the checked-in 9.6.0 visual release evidence for that
+product flow.
 
 ### 1. Wake Brain
 
@@ -124,21 +132,21 @@ confirm owner, check the computer, choose the Brain voice.
 Choose the owner of the Brain. The profile is not a SaaS account by default; it
 is the local identity for the knowledge you keep.
 
-![Login](output/release/v9.5.0/screenshots/01-login.png)
+![Login](output/release/v9.7.0/screenshots/01-login.png)
 
 ### 3. Recommended Models
 
 Start with a short list: safest recommendation, faster model, stronger model.
 Advanced details stay available without overwhelming first-time users.
 
-![Recommended Models](output/release/v9.5.0/screenshots/02-recommended-models.png)
+![Recommended Models](output/release/v9.7.0/screenshots/02-recommended-models.png)
 
 ### 4. Install And Load
 
 Download and load only after consent. Lattice explains model size, local
 execution, and network use before work starts.
 
-![Install and Load](output/release/v9.5.0/screenshots/03-install-load-progress.png)
+![Install and Load](output/release/v9.7.0/screenshots/03-install-load-progress.png)
 
 ### 5. Brain Chat
 
@@ -150,14 +158,14 @@ and its visible life signal follow real listening, recall, synthesis, and action
 state. Detailed memory rings, provenance, conversation history, and
 model/runtime proof open as overlays only when requested.
 
-![One-viewport Living Brain Home](output/release/v9.5.0/screenshots/04-brain-chat-home.png)
+![One-viewport Living Brain Home](output/release/v9.7.0/screenshots/04-brain-chat-home.png)
 
 ### 6. Review Center
 
 Automation results are staged for review before they become durable decisions.
 Snooze, unsnooze, run now, approve, and dismiss actions stay explicit.
 
-![Review Center](output/release/v9.5.0/screenshots/12-review-center.png)
+![Review Center](output/release/v9.7.0/screenshots/12-review-center.png)
 
 ## Brain Depths
 
@@ -173,10 +181,10 @@ The user travels inward from everyday memory to deeper structure:
 
 Walkthrough:
 
-![v9.5.0 Living Brain walkthrough](output/release/v9.5.0/gifs/v9.5.0-living-brain-walkthrough.gif)
+![v9.7.0 Living Brain walkthrough](output/release/v9.7.0/gifs/v9.7.0-living-brain-walkthrough.gif)
 
 Screenshot index and capture notes:
-[output/release/v9.5.0/SCREENSHOT_INDEX.md](output/release/v9.5.0/SCREENSHOT_INDEX.md)
+[output/release/v9.7.0/SCREENSHOT_INDEX.md](output/release/v9.7.0/SCREENSHOT_INDEX.md)
 
 ## Install
 
@@ -261,45 +269,59 @@ See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for developer workflow details.
 
 ## Current Release
 
-The current release is **9.5.0 — Command Center**:
-
-- A new `CommandCenterService` (`/api/command/briefing`, `/api/command/search`)
-  aggregates every Brain surface read-only and deterministically: recent
-  knowledge from the scoped graph, conversation activity, automation
-  enable/draft counts, pending review items, a Brain-health snapshot, and the
-  top automation suggestions — each section degrades independently when a
-  backend is unavailable.
-- State-derived quick actions with stable ids ("N items waiting for review",
-  "enable your draft automations", "connect a knowledge folder") give the UI
-  one-click jumps that always reflect the actual product state.
-- Universal search groups results across knowledge nodes (scoped keyword
-  search), the user's own conversations (deduped per conversation, newest
-  first), and installed automations — all scoped to the requesting user and
-  workspace.
-- The frontend gains a Cmd+K Command Palette (grouped results, keyboard
-  navigation, page jumps, fully ko/en localized) and a Today's Briefing panel
-  on the Brain home with stat chips, recent knowledge, and quick actions.
-- Everything is read-only, local, and model-free: no model calls, no writes,
-  no external actions.
-
-Expected artifacts for 9.5.0 release must use exact filenames:
-
-- `dist/ltcai-9.5.0-py3-none-any.whl`
-- `dist/ltcai-9.5.0.tar.gz`
-- `ltcai-9.5.0.tgz`
-- `dist/ltcai-9.5.0.vsix`
-- `src-tauri/target/release/bundle/dmg/Lattice AI_9.5.0_aarch64.dmg`
+The current release is **9.7.0 — Proactive Hybrid Brain**:
+
+- Retrieval is unified: `KnowledgeGraphStore.hybrid_search()` fuses lexical
+  and vector search in the graph layer itself (normalized scores, per-source
+  provenance, rank fusion), degrades honestly to `lexical_only` when the
+  vector index is unavailable, and `context_for_query()` can opt into it.
+- The vector index stays in sync automatically: every successful ingest runs
+  an incremental `index_node_incremental()` pass (opt-out via
+  `LATTICEAI_AUTO_VECTOR_INDEX`), and failures downgrade to an explicit
+  `pending` status that the next `rebuild_vector_index` picks up.
+- Ingestion covers whole folders: `ingest_folder()` walks directories with
+  `.latticeignore` support (gitignore-like globs), size/extension filters,
+  and optional background scheduling; `ingest_web_page()` formalizes the
+  web seam — fetching/parsing stays upstream, the graph receives clean text.
+- The Brain is proactive in the graph layer: `lattice_brain/graph/proactive.py`
+  finds duplicate and contradictory knowledge, produces a combined quality
+  report with stale-node and edge-quality signals, and plans consent-first
+  duplicate consolidation — surfaced at `GET /api/brain/duplicates`,
+  `GET /api/brain/quality-report`, and the existing contradiction/consolidate
+  endpoints.
+- The change-governance loop is closed: Review Center approval now applies
+  staged proposals through the single application path (no more
+  status-only approvals), proposals carry tool/risk/change-class/conversation
+  provenance, reject records a reason, and pending-proposal counts badge the
+  review inbox.
+- The agent evaluation gate grew to 12 scenarios, adding file-generation
+  happy path and recovery, a 3-step multi-step workflow chain, and a
+  governed-write proposal path that pins the approve()-excludes-governed-tools
+  invariant.
+- Engineering health: `SingleAgentRuntime.execute` decomposed into focused
+  helpers, multi-agent/single-agent runtime consistency pinned by tests, all
+  root legacy modules emit deprecation warnings pointing at their package
+  homes, and `scripts/profile_kg.py` + `docs/PERFORMANCE.md` establish a
+  measured KG performance baseline.
+
+Expected artifacts for 9.7.0 release must use exact filenames:
+
+- `dist/ltcai-9.7.0-py3-none-any.whl`
+- `dist/ltcai-9.7.0.tar.gz`
+- `ltcai-9.7.0.tgz`
+- `dist/ltcai-9.7.0.vsix`
+- `src-tauri/target/release/bundle/dmg/Lattice AI_9.7.0_aarch64.dmg`
 
 Do not use wildcard artifact uploads. Package registry publishing remains owner-run.
 
 See [docs/ROADMAP_RECOMMENDATIONS.md](docs/ROADMAP_RECOMMENDATIONS.md) for the
-strategic roadmap slices applied through 9.5.0 and the follow-up tracks.
+strategic roadmap slices applied through 9.7.0 and the follow-up tracks.
 
 ## Known Limitations
 
 - 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 9.5.0.
+  live local Brain store in 9.7.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.
@@ -311,6 +333,8 @@ strategic roadmap slices applied through 9.5.0 and the follow-up tracks.
 
 | Version | Theme |
 | --- | --- |
+| 9.7.0 | Proactive Hybrid Brain: graph-native hybrid lexical+vector retrieval with automatic incremental vector indexing, folder ingestion with `.latticeignore`, proactive duplicate/contradiction detection and quality reporting in the graph layer, and a fully closed proposal→Review Center→apply governance loop |
+| 9.6.0 | Trusted Agent Loop: observable agent reasoning (LoopTrace + loop API payload), python-literal/fence/think weak-model repairs with escalating corrections, a deterministic CI agent-eval harness, and proposal-first change governance where edits/deletions of existing files become reviewable diffs |
 | 9.5.0 | Command Center: a Cmd+K palette searching knowledge, conversations, automations, and pages in one query, plus a daily briefing with Brain state at a glance and state-derived one-click quick actions |
 | 9.4.0 | Question-Driven Everyday Automation: the Brain mines recurring user questions and connected knowledge folders into one-click, consent-first automation suggestions installed as review-gated drafts |
 | 9.3.0 | Proactive Brain Intelligence: the Brain diagnoses its own health, surfaces contradictions and stale knowledge, proposes consent-first duplicate consolidation, and recalls with hybrid lexical+semantic evidence behind an honest quality gate |

package/auto_setup.py

@@ -1,6 +1,16 @@
 """Compatibility shim for :mod:`latticeai.setup.auto_setup`."""
 
-from latticeai.setup import auto_setup as _impl
+import warnings
+
+warnings.warn(
+    "Importing 'auto_setup' from the repository root is deprecated; "
+    "use 'from latticeai.setup import auto_setup' instead. "
+    "The root shim will be removed in a future major release.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+from latticeai.setup import auto_setup as _impl  # noqa: E402
 
 
 if __name__ == "__main__":

package/docs/CHANGELOG.md

@@ -4,6 +4,92 @@ 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.
 
+## [9.7.0] - 2026-07-20
+
+### Added
+- Added `KnowledgeGraphStore.hybrid_search()`: graph-native fusion of
+  lexical and vector retrieval with normalized scores, per-source
+  provenance, chunk→parent roll-up, workspace scoping, and an honest
+  `lexical_only` fallback; `context_for_query()` gains an opt-in
+  `use_hybrid` flag.
+- Added `index_node_incremental()` and automatic post-ingest vector-index
+  sync in `IngestionPipeline` (opt-out `LATTICEAI_AUTO_VECTOR_INDEX`);
+  vector failures downgrade to `indexing_status: pending` instead of
+  failing the ingest.
+- Added `IngestionPipeline.ingest_folder()` (recursive walk,
+  `.latticeignore` gitignore-like filtering, size/extension limits,
+  optional background queue) and `ingest_web_page()` (formalized
+  extracted-text web seam; fetching/parsing stays upstream).
+- Added `lattice_brain/graph/proactive.py` (`ProactiveBrain`): duplicate
+  detection, contradiction detection, combined `quality_report()`,
+  consent-first `consolidate_duplicates()` planning, and the pure
+  `gate_ingest_candidate()` quality-gating seam.
+- Added `GET /api/brain/duplicates` and `GET /api/brain/quality-report`;
+  `/api/brain/contradictions` and `/api/brain/consolidate` return
+  graph-layer results additively.
+- Added `GET /api/proposals/counts`, `GET /api/proposals/{id}` (diff +
+  staged content), reject-with-reason, and
+  `GET /automation/reviews/counts`; the Review Center UI gains a
+  `change_proposal` filter, diff preview, tier/deletion badges, a
+  pending-count badge, and a reject-reason input (ko/en parity).
+- Added 4 agent-eval scenarios (12 total): file-generation happy path,
+  file-generation recovery, multi-step workflow chain, and a
+  governed-write proposal path pinning the
+  approve()-excludes-governed-tools invariant.
+- Added `tests/unit/test_runtime_consistency.py`,
+  `scripts/profile_kg.py`, and `docs/PERFORMANCE.md` (measured synthetic
+  KG baseline; flags brute-force `vector_search()` as the next
+  optimization target).
+
+### Changed
+- Review Center approval of `change_proposal` items now applies the staged
+  content through `ChangeProposalService.approve_and_apply` (single
+  application path, 409 on replay) instead of only flipping status.
+- Change proposals carry tool/risk/change-class/conversation-id
+  provenance; the agent loop forwards `conversation_id` to the governor.
+- `SingleAgentRuntime.execute` decomposed into six focused helpers
+  (behavior-preserving); the multi-agent orchestrator surfaces real
+  failure reasons in `execution_failed` timeline events.
+- All root legacy modules emit `DeprecationWarning` pointing at their
+  package homes; the legacy-compatibility registry tracks all 13 shims.
+
+### Security
+- Proposal apply/reject stays fail-closed end-to-end: approval applies
+  exactly the reviewed staged content, replays are rejected with 409, and
+  reject reasons land in provenance for audit.
+
+## [9.6.0] - 2026-07-20
+
+### Added
+- Added `latticeai/core/agent_trace.py` (`LoopTrace`): typed observability
+  for the single-agent reasoning loop, returned as `loop` with every agent
+  API response.
+- Added `latticeai/core/agent_eval.py` + `scripts/agent_eval.py`: a
+  deterministic scripted-model evaluation harness over the real agent state
+  machine, wired into CI as a release gate.
+- Added `latticeai/core/tool_governor.py` and
+  `latticeai/services/change_proposals.py` + `/api/proposals` router:
+  central read/additive/mutation/destructive classification with
+  proposal-first governance — edits/deletions of existing files are staged
+  as review-queue proposals (source `change_proposal`) with unified diffs
+  and applied exactly as reviewed on approval.
+- Added the "변경 제안 / Change proposals" Brain home panel with diff
+  previews and one-click approve/reject.
+
+### Changed
+- The action parser tolerates Python-literal dicts and reports every repair
+  by name; repeated formatting slips escalate the correction with the valid
+  tool list.
+- Additive file creates in the agent loop run without plan-approval
+  friction; plan approval no longer hard-blocks governor-managed tools.
+- Ruff per-file lint ignores trimmed from 9 entries to 3.
+
+### Security
+- Mutations and deletions of existing workspace files by the agent can no
+  longer apply silently: they stage as reviewable proposals, and approve
+  applies the exact reviewed content with full audit events.
+- AGENTS.md is now inside the machine-checked release documentation gate.
+
 ## [9.5.0] - 2026-07-20
 
 ### Added

package/docs/COMMUNITY_AND_PLUGINS.md

@@ -1,13 +1,13 @@
 # Community And Plugins
 
-Current release: **9.5.0 — Command Center**.
+Current release: **9.7.0 — Proactive Hybrid Brain**.
 
 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
 reliability, 8.7.0 runtime-state hygiene, 8.8.0 Brain Core extraction
 readiness, 8.9.0 scoped Tool API hardening, 9.0.0 cleanup closure, 9.1.0
 fail-closed review completion, 9.2.0 model-agnostic file generation, 9.3.0
-proactive Brain intelligence, 9.4.0 question-driven everyday automation, and 9.5.0 Command Center)
+proactive Brain intelligence, 9.4.0 question-driven everyday automation, 9.5.0 Command Center, and 9.6.0 Trusted Agent Loop)
 to a product ecosystem. The
 immediate goal is small and practical: make it clear how
 contributors can extend the Brain without weakening local-first trust,

package/docs/DEVELOPMENT.md

@@ -1,10 +1,10 @@
 # Lattice AI Development
 
-Current release: **9.5.0 — Command Center**.
+Current release: **9.7.0 — Proactive Hybrid Brain**.
 
 This document is for contributors working on the local-first Digital Brain
 codebase. Product positioning and quick start stay in `README.md`; release
-history is intentionally limited to 8.0.0-9.5.0 in `docs/CHANGELOG.md` and
+history is intentionally limited to 8.0.0-9.6.0 in `docs/CHANGELOG.md` and
 `RELEASE.md`.
 
 ## Product Contract
@@ -153,10 +153,10 @@ For user-facing, API, runtime, release, or packaging changes, check:
 Release/publish examples must use exact target-version filenames. Do not
 document wildcard artifact upload commands.
 
-For 9.5.0 release work, exact artifacts are:
+For 9.6.0 release work, exact artifacts are:
 
-- `dist/ltcai-9.5.0-py3-none-any.whl`
-- `dist/ltcai-9.5.0.tar.gz`
-- `ltcai-9.5.0.tgz`
-- `dist/ltcai-9.5.0.vsix`
-- `src-tauri/target/release/bundle/dmg/Lattice AI_9.5.0_aarch64.dmg`
+- `dist/ltcai-9.6.0-py3-none-any.whl`
+- `dist/ltcai-9.6.0.tar.gz`
+- `ltcai-9.6.0.tgz`
+- `dist/ltcai-9.6.0.vsix`
+- `src-tauri/target/release/bundle/dmg/Lattice AI_9.6.0_aarch64.dmg`

package/docs/LEGACY_COMPATIBILITY.md

@@ -1,6 +1,6 @@
 # Legacy Compatibility Map
 
-Current target: **9.5.0 — Command Center**.
+Current target: **9.6.0 — Trusted Agent Loop**.
 
 Lattice AI is moving toward a smaller, modular architecture centered on
 `lattice_brain`, `latticeai.services`, `latticeai.api`, and `latticeai.runtime`.

package/docs/ONBOARDING.md

@@ -1,6 +1,6 @@
 # Lattice AI Onboarding
 
-Current release: **9.5.0 — Command Center**.
+Current release: **9.7.0 — Proactive Hybrid Brain**.
 
 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
@@ -40,7 +40,7 @@ read the docs first.
 
 ## Release Gate
 
-9.5.0 treats onboarding as a release gate, not marketing copy. The current
+9.6.0 treats onboarding as a release gate, not marketing copy. The current
 machine-checkable product readiness report requires this five-minute contract,
 the Brain Home surface, setup helpers, graph ingestion tests, and exact release
 artifact documentation before the release can be called complete.

package/docs/OPERATIONS.md

@@ -1,4 +1,4 @@
-# Lattice AI — Operations Guide (v9.5.0)
+# Lattice AI — Operations Guide (v9.6.0)
 
 ## 1. 데이터 파일 위치
 

package/docs/PERFORMANCE.md

@@ -0,0 +1,106 @@
+# Knowledge Graph Performance Baseline
+
+Synthetic performance and memory baseline for `KnowledgeGraphStore`
+(`lattice_brain/graph/`). Measured with `scripts/profile_kg.py`.
+
+**This is a synthetic baseline, not a real-workload benchmark.** Use it for
+release-over-release regression comparison, not as a marketing number.
+
+## Methodology
+
+- `scripts/profile_kg.py` builds a throwaway store the same way the unit tests
+  do (`KnowledgeGraphStore(tmp/graph.sqlite, tmp/blobs)`) and ingests N
+  synthetic text sources through the real `ingest_source()` pipeline
+  (chunking, rule-based concept/triple extraction, provenance edges).
+- Corpus: fixed-vocabulary English + Korean text, seeded RNG (`--seed`,
+  default 42), ~60% short (~40 words) / 30% medium (~160) / 10% long (~520)
+  documents with recurring entities so concept nodes are shared and edges form.
+- Fully offline: no LLM router is registered (extraction takes the rules
+  path) and the embedder is the built-in deterministic hash model. No network,
+  no model downloads.
+- Timing: `time.perf_counter()` per call; p50/p95/mean over all calls in a
+  phase. Memory: `tracemalloc` peak, reset per phase.
+- Caveat: tracemalloc runs for the whole profile and roughly doubles Python
+  allocation cost, so absolute timings are conservative upper bounds.
+- Caveat: the synthetic vocabulary is small, so FTS selectivity and concept
+  density differ from real user data; every tenth query is a guaranteed miss
+  to avoid measuring only warm hits.
+
+Run it:
+
+```bash
+.venv/bin/python scripts/profile_kg.py                 # 5000 sources, 50 queries
+.venv/bin/python scripts/profile_kg.py --nodes 500     # quick run (~10 s)
+.venv/bin/python scripts/profile_kg.py --json          # machine-readable
+```
+
+## Measured baseline (2026-07-20, v9.6.0 working tree)
+
+Apple Silicon (darwin), Python 3.x from `.venv`, SQLite with FTS5 trigram
+available, tracemalloc enabled.
+
+### 500 sources (quick profile, ~9 s total)
+
+Graph produced: 2,019 nodes / 6,546 edges, 21.2 MB SQLite file.
+
+| phase                | calls | p50 ms | p95 ms | wall s | peak MB |
+|----------------------|------:|-------:|-------:|-------:|--------:|
+| ingest_source        |   500 |   6.9  |  17.7  |   4.1  |   0.6   |
+| search               |    50 |   1.2  |   2.5  |   0.07 |   0.6   |
+| context_for_query    |    50 |   1.0  |   2.4  |   0.06 |   0.5   |
+| neighbors            |    50 |   0.35 |   0.45 |   0.02 |   0.6   |
+| traverse (depth 2)   |    50 |   4.8  |   5.2  |   0.24 |   1.1   |
+| stats                |     5 |   1.5  |   1.7  |   0.01 |   0.4   |
+| rebuild_vector_index |     1 |  1319  |  1319  |   1.3  |   5.0   |
+| vector_search        |    10 |  287   |  294   |   2.9  |  14.4   |
+
+Ingestion throughput: **~122 items/sec** (412 KB corpus).
+
+### 5000 sources (default profile, ~2.5 min total)
+
+Graph produced: 18,426 nodes / 62,534 edges, 198.8 MB SQLite file
+(4.26 MB corpus). Measured while other processes shared the CPU, so treat as
+an upper bound.
+
+| phase                | calls | p50 ms | p95 ms | wall s | peak MB |
+|----------------------|------:|-------:|-------:|-------:|--------:|
+| ingest_source        |  5000 |  20.1  |  54.6  | 119.9  |   1.4   |
+| search               |    50 |   4.3  |  19.8  |   0.40 |   1.2   |
+| context_for_query    |    50 |   4.1  |  18.5  |   0.40 |   1.2   |
+| neighbors            |    50 |   0.39 |   0.50 |   0.03 |   1.2   |
+| traverse (depth 2)   |    50 |  12.2  |  15.8  |   0.64 |   1.7   |
+| stats                |     5 |  13.1  |  13.5  |   0.07 |   1.1   |
+| rebuild_vector_index |     1 | 14624  | 14624  |  14.6  |  45.6   |
+| vector_search        |    10 |  1732  |  1774  |  17.4  |  83.5   |
+
+Ingestion throughput: **~42 items/sec** at this scale.
+
+Scaling signal (500 → 5000 sources, 10x): per-item ingest p50 grew ~3x
+(6.9 ms → 20.1 ms) — ingestion cost is superlinear in DB size (FTS triggers,
+dedup lookups, edge upserts against growing tables). `vector_search` p50 grew
+~6x (287 ms → 1732 ms), consistent with its O(index size) brute-force scan.
+Keyword search p50 grew ~3.6x but stays under 5 ms.
+
+Regenerate with `.venv/bin/python scripts/profile_kg.py` after graph-layer
+changes and compare against these tables.
+
+## 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.
+- `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.
+
+## Regression workflow
+
+1. Before a graph-layer change: `.venv/bin/python scripts/profile_kg.py --nodes 500 --json > /tmp/kg-before.json`
+2. After the change: same command to `/tmp/kg-after.json`.
+3. Compare phase p50/p95 and `db_size_mb`; investigate anything that moved
+   more than ~20% beyond run-to-run noise.

package/docs/TRUST_MODEL.md

@@ -1,6 +1,6 @@
 # Lattice AI Trust Model
 
-Current release: **9.5.0 — Command Center**.
+Current release: **9.7.0 — Proactive Hybrid Brain**.
 
 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: **9.5.0 — Command Center**.
+Current release: **9.7.0 — Proactive Hybrid Brain**.
 
 **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: **9.5.0 — Command Center**.
+Current release: **9.7.0 — Proactive Hybrid Brain**.
 
 명세 출처: `lattice_ai_full_spec.pptx` 슬라이드 20·21·22
 구현: `kg_schema.py`

package/docs/mcp-tools.md

@@ -1,4 +1,4 @@
-# MCP 도구 카탈로그 (v9.5.0)
+# MCP 도구 카탈로그 (v9.6.0)
 
 Lattice AI는 MCP(Model Context Protocol) 서버로 동작하여 Claude Desktop, Cursor 등에서 직접 도구를 사용할 수 있습니다.
 

package/kg_schema.py

@@ -1,3 +1,13 @@
 """Compatibility shim for the v4 Knowledge Graph schema."""
 
-from lattice_brain.graph.schema import *  # noqa: F403,F401
+import warnings as _warnings
+
+_warnings.warn(
+    "Importing 'kg_schema' from the repository root is deprecated; "
+    "use 'from lattice_brain.graph.schema import ...' instead. "
+    "The root shim will be removed in a future major release.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+from lattice_brain.graph.schema import *  # noqa: F403,F401,E402

package/knowledge_graph.py

@@ -4,7 +4,17 @@ The implementation now lives under :mod:`lattice_brain`. Root imports are
 kept for older integrations and tests.
 """
 
-from lattice_brain.graph._kg_common import (  # noqa: F401
+import warnings as _warnings
+
+_warnings.warn(
+    "Importing 'knowledge_graph' from the repository root is deprecated; "
+    "use 'from lattice_brain.graph.store import KnowledgeGraphStore' instead. "
+    "The root shim will be removed in a future major release.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+from lattice_brain.graph._kg_common import (  # noqa: F401,E402
     EDGE_VERB,
     GRAPH_SCHEMA_VERSION,
     LOCAL_CODE_EXTENSIONS,
@@ -24,7 +34,7 @@ from lattice_brain.graph._kg_common import (  # noqa: F401
     _slug,
     set_llm_router,
 )
-from lattice_brain.graph.store import KnowledgeGraphStore
+from lattice_brain.graph.store import KnowledgeGraphStore  # noqa: E402
 
 __all__ = [
     "KnowledgeGraphStore",

package/knowledge_graph_api.py

@@ -6,7 +6,17 @@ importable for the deprecation window and will be removed in a future major
 release.
 """
 
-from latticeai.api.knowledge_graph import (  # noqa: F401
+import warnings as _warnings
+
+_warnings.warn(
+    "Importing 'knowledge_graph_api' from the repository root is deprecated; "
+    "use 'from latticeai.api.knowledge_graph import create_knowledge_graph_router' instead. "
+    "The root shim will be removed in a future major release.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+from latticeai.api.knowledge_graph import (  # noqa: F401,E402
     KnowledgeGraphIngestRequest,
     create_knowledge_graph_router,
 )

package/lattice_brain/__init__.py

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