ltcai 8.6.0 → 8.8.0

package/README.md

@@ -1,6 +1,6 @@
 # Lattice AI
 
-**Lattice AI 8.6.0 is the local-first Digital Brain platform. This release fixes desktop folder selection for the Tauri localhost app, improves Capture feedback for folder and web source saving, and aligns the new Brain shell navigation with CI-verified visual coverage.**
+**Lattice AI 8.8.0 is the local-first Digital Brain platform. This release removes internal-only Brain compatibility layers, strengthens recall proof quality, and keeps package, desktop, extension, static app, and documentation metadata synchronized to the 8.8.0 line.**
 
 **Lattice AI는 모델이 바뀌어도 내 지식과 맥락을 보존하는 로컬 우선 AI 브레인입니다.**
 
@@ -64,10 +64,10 @@ You need Lattice AI when:
 
 ## Living Brain Flow
 
-The screenshots below are the latest checked-in visual evidence captures from
-the 8.2 Brain Home release. The 8.3 line keeps that first-run flow focused on
-the Brain while adding clearer onboarding, stronger workflow/runtime
-boundaries, and better ingestion proof behind the scenes.
+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
+8.8.0 focuses on Brain Core extraction readiness and recall proof hardening.
 
 ### 1. Wake Brain
 
@@ -79,21 +79,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/v8.2.0/screenshots/01-login.png)
+![Login](output/release/v8.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/v8.2.0/screenshots/02-recommended-models.png)
+![Recommended Models](output/release/v8.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/v8.2.0/screenshots/03-install-load-progress.png)
+![Install and Load](output/release/v8.7.0/screenshots/03-install-load-progress.png)
 
 ### 5. Brain Chat
 
@@ -101,14 +101,14 @@ Talk normally. Useful decisions and context become memory, then appear later as
 topics, relationships, graph structure, and the concentric memory rings around
 the Brain.
 
-![Brain Brief Home](output/release/v8.2.0/screenshots/04-brain-chat-home.png)
+![Brain Brief Home](output/release/v8.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/v8.2.0/screenshots/12-review-center.png)
+![Review Center](output/release/v8.7.0/screenshots/12-review-center.png)
 
 ## Brain Depths
 
@@ -124,10 +124,10 @@ The user travels inward from everyday memory to deeper structure:
 
 Walkthrough:
 
-![v8.2.0 Living Brain walkthrough](output/release/v8.2.0/gifs/v8.2.0-living-brain-walkthrough.gif)
+![v8.7.0 Living Brain walkthrough](output/release/v8.7.0/gifs/v8.7.0-living-brain-walkthrough.gif)
 
 Screenshot index and capture notes:
-[output/release/v8.2.0/SCREENSHOT_INDEX.md](output/release/v8.2.0/SCREENSHOT_INDEX.md)
+[output/release/v8.7.0/SCREENSHOT_INDEX.md](output/release/v8.7.0/SCREENSHOT_INDEX.md)
 
 ## Install
 
@@ -190,7 +190,6 @@ Main validation set:
 
 ```bash
 npm run check:python
-node scripts/run_python.mjs -m ruff check .
 npm run lint
 npm run typecheck
 npm run test:unit
@@ -200,34 +199,40 @@ npm run desktop:tauri:check
 npm run docs:check-links
 ```
 
+`npm run lint` includes the Python Ruff baseline, frontend TypeScript lint
+gate, visual smoke syntax checks, and i18n literal checks.
+
 See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for developer workflow details.
 
 ## Current Release
 
-The current release is **8.6.0 — Desktop Capture & Navigation Reliability**:
-
-- The desktop Capture flow can open a native folder picker from the Tauri
-  localhost app, fill the selected path, and immediately scan/connect it.
-- Folder picker failures now surface an actionable message instead of silently
-  doing nothing, while manual path entry remains available.
-- Web page capture keeps paste, Enter-to-save, and `https://` normalization for
-  bare domains.
-- The Brain shell sidebar/navigation and admin entry points are covered by
-  updated Visual Smoke tests, while the 8.5 ToolRegistry and Config DI
-  hardening remains active.
-
-Expected artifacts for 8.6.0 release must use exact filenames:
-
-- `dist/ltcai-8.6.0-py3-none-any.whl`
-- `dist/ltcai-8.6.0.tar.gz`
-- `ltcai-8.6.0.tgz`
-- `dist/ltcai-8.6.0.vsix`
-- `src-tauri/target/release/bundle/dmg/Lattice AI_8.6.0_aarch64.dmg`
+The current release is **8.8.0 — Brain Core Extraction & Recall Proof Hardening**:
+
+- Internal-only Brain shim layers are removed: pre-graph flat modules,
+  the deprecated `latticeai.brain` namespace, and the service-layer
+  AgentRuntime alias are tracked as intentional 8.8.0 removals.
+- Root compatibility shims remain managed for external entrypoints while Brain
+  Core now has one physical import surface guarded by isolation tests.
+- AgentRuntime rejects unknown roles at the boundary, exposes contract envelopes
+  for legacy run rows, and persists clamped retry budgets.
+- Brain Chat adds resumable conversation history, stop/regenerate/copy actions,
+  richer ingestion panels, and answer proof explainability with matched terms
+  and confidence labels.
+- Memory recall drops zero-evidence noise when lexical evidence exists, so
+  citations explain why each source was selected.
+
+Expected artifacts for 8.8.0 release must use exact filenames:
+
+- `dist/ltcai-8.8.0-py3-none-any.whl`
+- `dist/ltcai-8.8.0.tar.gz`
+- `ltcai-8.8.0.tgz`
+- `dist/ltcai-8.8.0.vsix`
+- `src-tauri/target/release/bundle/dmg/Lattice AI_8.8.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 8.6.0 and the follow-up tracks.
+strategic roadmap slices applied through 8.8.0 and the follow-up tracks.
 
 ## Known Limitations
 
@@ -244,6 +249,8 @@ strategic roadmap slices applied through 8.6.0 and the follow-up tracks.
 
 | Version | Theme |
 | --- | --- |
+| 8.8.0 | Brain Core Extraction & Recall Proof Hardening: internal-only Brain shim layers are removed, AgentRuntime run contracts/retry budgets are tighter, Brain Chat gains conversation controls, and citation recall exposes matched evidence |
+| 8.7.0 | Runtime State Hygiene & Release Evidence Refresh: model-runtime internals prefer typed state over legacy globals, compatibility sync is deprecated, 8.7.0 visual evidence is refreshed, and all release metadata/docs are synchronized |
 | 8.6.0 | Desktop Capture & Navigation Reliability: native folder selection works from the Tauri localhost app, picker failures surface in Capture, web saving remains one-action, and the Brain shell sidebar/admin flow is CI-covered |
 | 8.5.0 | Tool Registry Readiness & Config DI: ToolRegistry drift removed, `tz_name` flows through central Config into automation runtimes, and current-release documentation is synchronized |
 | 8.4.0 | Action-Aware Brain Chat: explicit file create/write/save/edit requests from Brain Chat route into the governed workspace file tool so files are actually created instead of returned as code-only answers |

package/docs/CHANGELOG.md

@@ -6,7 +6,55 @@ existed at that release.
 
 ## [Unreleased]
 
-No unreleased changes.
+## [8.8.0] - 2026-07-06
+
+### Added
+- Added Brain Core isolation coverage that keeps `lattice_brain` independent of
+  product-package imports.
+- Added recall proof quality gates for matched terms, confidence labels, and
+  lexical evidence filtering.
+- Added Brain Chat conversation controls for new/resume/delete, stop,
+  regenerate, copy, and richer ingestion progress.
+
+### Changed
+- Removed internal-only Brain shim layers: flat pre-graph modules,
+  `latticeai.brain`, and `latticeai.services.agent_runtime`.
+- Updated legacy compatibility reporting so removed shim layers are tracked
+  separately from remaining external root shims.
+- Hardened AgentRuntime boundary handling for unknown roles, legacy run
+  contracts, and persisted retry budgets.
+- Version bumped to 8.8.0 across Python, npm, VS Code extension, Tauri, static
+  metadata, readiness gates, release notes, and current-release documentation.
+
+### Fixed
+- File ingestion now rejects directory paths before dispatching to document
+  ingestion.
+- Memory recall filters low-evidence noise when stronger lexical matches are
+  present and surfaces explainable citation confidence.
+
+## [8.7.0] - 2026-07-05
+
+### Added
+- Added unit test coverage for model-runtime `STATE` source-of-truth behavior
+  and deprecation warnings on legacy global synchronization.
+- Added refreshed 8.7.0 screenshots, walkthrough GIF/WebM, and capture notes
+  under `output/release/v8.7.0/`.
+
+### Changed
+- Reduced internal reliance on bare module globals in
+  `latticeai/services/model_runtime.py`; implementation logic now consistently
+  reads from the `ModelRuntimeState` instance while globals remain as a legacy
+  compatibility surface.
+- Added `DeprecationWarning` to `sync_to_module_globals()` while preserving the
+  external shim behavior.
+- Removed a loose `as any` cast from `frontend/src/pages/Act.tsx`.
+- Version bumped to 8.7.0 across Python, npm, VS Code extension, Tauri, static
+  metadata, README evidence links, release notes, and current-release
+  documentation.
+
+### Fixed
+- Internal model-runtime functions now prefer the typed state object per the
+  project preference for composition over global mutable state.
 
 ## [8.6.0] - 2026-07-05
 

package/docs/COMMUNITY_AND_PLUGINS.md

@@ -1,9 +1,12 @@
 # Community And Plugins
 
-Current release: **8.6.0 — Desktop Capture & Navigation Reliability**.
+Current release: **8.8.0 — Brain Core Extraction & Recall Proof Hardening**.
 
-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) to a
-product ecosystem. The immediate goal is small and practical: make it clear how
+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, and 8.8.0 Brain Core extraction
+readiness) 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,
 workspace scoping, or release quality.
 
@@ -34,7 +37,7 @@ Plugins should add one bounded capability at a time:
 - Compatibility requirements belong in `lattice_version`, and examples should
   use current host-compatible values.
 
-## 8.4.0 Ecosystem Tasks
+## Current Ecosystem Tasks
 
 - Keep the hello-world plugin valid and boring.
 - Expand examples only when they exercise real extension seams.

package/docs/DEVELOPMENT.md

@@ -1,10 +1,10 @@
 # Lattice AI Development
 
-Current release: **8.6.0 — Desktop Capture & Navigation Reliability**.
+Current release: **8.8.0 — Brain Core Extraction & Recall Proof Hardening**.
 
 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 7.0.0-8.6.0 in `docs/CHANGELOG.md` and
+history is intentionally limited to 7.0.0-8.8.0 in `docs/CHANGELOG.md` and
 `RELEASE.md`.
 
 ## Product Contract
@@ -49,13 +49,15 @@ API, UI, or release work, run:
 
 ```bash
 npm run check:python
-node scripts/run_python.mjs -m ruff check .
 npm run lint
 npm run typecheck
 npm run test:unit
 npm run docs:check-links
 ```
 
+`npm run lint` runs the Python Ruff baseline, frontend TypeScript lint gate,
+visual smoke syntax checks, and i18n literal checks.
+
 Use these when the change touches the relevant surface:
 
 ```bash
@@ -112,10 +114,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 8.6.0 release work, exact artifacts are:
+For 8.8.0 release work, exact artifacts are:
 
-- `dist/ltcai-8.6.0-py3-none-any.whl`
-- `dist/ltcai-8.6.0.tar.gz`
-- `ltcai-8.6.0.tgz`
-- `dist/ltcai-8.6.0.vsix`
-- `src-tauri/target/release/bundle/dmg/Lattice AI_8.6.0_aarch64.dmg`
+- `dist/ltcai-8.8.0-py3-none-any.whl`
+- `dist/ltcai-8.8.0.tar.gz`
+- `ltcai-8.8.0.tgz`
+- `dist/ltcai-8.8.0.vsix`
+- `src-tauri/target/release/bundle/dmg/Lattice AI_8.8.0_aarch64.dmg`

package/docs/LEGACY_COMPATIBILITY.md

@@ -1,21 +1,40 @@
 # Legacy Compatibility Map
 
-Current release: **8.6.0 — Desktop Capture & Navigation Reliability**.
+Current target: **8.8.0 — Internal shim removal & Brain Core extraction prep**.
 
 Lattice AI is moving toward a smaller, modular architecture centered on
 `lattice_brain`, `latticeai.services`, `latticeai.api`, and `latticeai.runtime`.
 Some root-level modules remain packaged for compatibility with older imports,
 CLI entrypoints, or extension workflows. Their presence does not define the
-current 8.6.0 architecture.
+current architecture.
 
-8.6.0 also tracks the inner compatibility layers that sit below the root
-modules. The managed inventory lives in `latticeai.core.legacy_compatibility`
-and groups shims by layer:
+The managed inventory lives in `latticeai.core.legacy_compatibility` and
+groups shims by layer:
 
-- `root`: historical repo-root imports such as `knowledge_graph.py`.
-- `brain-flat`: pre-graph-package imports such as `lattice_brain.store`.
-- `deprecated-namespace`: older `latticeai.brain.*` package imports.
-- `service-alias`: service paths that now alias Brain runtime modules.
+- `root`: historical repo-root imports such as `knowledge_graph.py` — **kept**
+  (external entrypoints: `uvicorn server:app`, installed CLI, old scripts).
+- `brain-flat`: pre-graph-package imports such as `lattice_brain.store` —
+  **removed in 8.8.0** (internal-only).
+- `deprecated-namespace`: older `latticeai.brain.*` package imports —
+  **removed in 8.8.0** (internal-only).
+- `service-alias`: `latticeai.services.agent_runtime` —
+  **removed in 8.8.0** (internal-only).
+
+Removed layers stay listed in `legacy_compatibility.REMOVED_SHIMS` and in the
+`legacy_shim_report()` payload (`removed`, `lingering`), so tooling can tell
+"removed on purpose" apart from "missing by accident".
+
+## Brain Core extraction readiness
+
+Removing the internal layers gives `lattice_brain` exactly one import surface
+(its physical module paths). Two structural guards keep it extractable as a
+standalone package:
+
+- `tests/unit/test_brain_core_isolation.py` — AST guard that fails if any
+  `lattice_brain` module imports `latticeai` (the product imports the Brain,
+  never the reverse).
+- `tests/unit/test_legacy_root_shims.py::test_internal_shim_layers_are_gone`
+  — fails if a removed shim path becomes importable again.
 
 ## Current Policy
 
@@ -47,13 +66,13 @@ and groups shims by layer:
 | `setup_wizard.py` | setup and model recommendation services | Compatibility for first-run recommendation calls |
 | `server.py` | lazy proxy to `latticeai.server_app` / `latticeai.app_factory` | Preserves historical `server.app` imports without import-time construction |
 
-## Inner Shim Layers
+## Inner Shim Layers (removed in 8.8.0)
 
-| Legacy layer | Example module | Current home / direction | Why it remains |
+| Legacy layer | Example module | Replacement import | Status |
 | --- | --- | --- | --- |
-| `brain-flat` | `lattice_brain.store`, `lattice_brain.ingest`, `lattice_brain.retrieval` | `lattice_brain.graph.*` | Preserves imports from before graph modules were split into a package |
-| `deprecated-namespace` | `latticeai.brain.store`, `latticeai.brain.ingest` | `lattice_brain.graph.*` | Preserves the old application-package Brain namespace |
-| `service-alias` | `latticeai.services.agent_runtime` | `lattice_brain.runtime.agent_runtime` | Preserves service-layer imports while runtime ownership sits in Brain Core |
+| `brain-flat` | `lattice_brain.store`, `lattice_brain.ingest`, `lattice_brain.retrieval` | `lattice_brain.graph.*` | Removed — internal-only, no supported entrypoint depended on it |
+| `deprecated-namespace` | `latticeai.brain.*` | `lattice_brain.*` | Removed — namespace also dropped from `pyproject.toml` packages |
+| `service-alias` | `latticeai.services.agent_runtime` | `lattice_brain.runtime.agent_runtime` | Removed — runtime ownership sits in Brain Core |
 
 ## Packaging Notes
 

package/docs/ONBOARDING.md

@@ -1,6 +1,6 @@
 # Lattice AI Onboarding
 
-Current release: **8.6.0 — Desktop Capture & Navigation Reliability**.
+Current release: **8.8.0 — Brain Core Extraction & Recall Proof Hardening**.
 
 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
@@ -32,7 +32,7 @@ read the docs first.
 
 ## Release Gate
 
-8.6.0 treats onboarding as a release gate, not marketing copy. The current
+8.8.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/TRUST_MODEL.md

@@ -1,6 +1,6 @@
 # Lattice AI Trust Model
 
-Current release: **8.6.0 — Desktop Capture & Navigation Reliability**.
+Current release: **8.8.0 — Brain Core Extraction & Recall Proof Hardening**.
 
 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: **8.6.0 — Desktop Capture & Navigation Reliability**.
+Current release: **8.8.0 — Brain Core Extraction & Recall Proof Hardening**.
 
 **Lattice AI is a local-first Digital Brain that keeps your knowledge durable
 across any AI model.**
@@ -32,7 +32,7 @@ The graph matters, but it is not the product identity. The product identity is a
 local-first Digital Brain: a place where the user can talk, add sources, watch
 memory grow, and inspect the Knowledge Graph when they need proof.
 
-In 8.6.0 the first screen is intentionally not a dashboard. The living Brain,
+In 8.8.0 the first screen is intentionally not a dashboard. The living Brain,
 conversation composer, evidence-backed Brain Brief, and five-minute onboarding
 path appear together so the user immediately knows what matters, what to add,
 and why the answer is grounded in local memory.

package/docs/kg-schema.md

@@ -1,6 +1,6 @@
 # Knowledge Graph Schema
 
-Current release: **8.6.0 — Desktop Capture & Navigation Reliability**.
+Current release: **8.8.0 — Brain Core Extraction & Recall Proof Hardening**.
 
 명세 출처: `lattice_ai_full_spec.pptx` 슬라이드 20·21·22
 구현: `kg_schema.py`

package/kg_schema.py

@@ -1,3 +1,3 @@
 """Compatibility shim for the v4 Knowledge Graph schema."""
 
-from lattice_brain.schema import *  # noqa: F403,F401
+from lattice_brain.graph.schema import *  # noqa: F403,F401

package/knowledge_graph.py

@@ -4,7 +4,7 @@ The implementation now lives under :mod:`lattice_brain`. Root imports are
 kept for older integrations and tests.
 """
 
-from lattice_brain._kg_common import (  # noqa: F401
+from lattice_brain.graph._kg_common import (  # noqa: F401
     EDGE_VERB,
     GRAPH_SCHEMA_VERSION,
     LOCAL_CODE_EXTENSIONS,
@@ -24,7 +24,7 @@ from lattice_brain._kg_common import (  # noqa: F401
     _slug,
     set_llm_router,
 )
-from lattice_brain.store import KnowledgeGraphStore
+from lattice_brain.graph.store import KnowledgeGraphStore
 
 __all__ = [
     "KnowledgeGraphStore",

package/lattice_brain/__init__.py

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

package/lattice_brain/core.py

@@ -40,7 +40,7 @@ class BrainCore:
             )
 
         from .conversations import ConversationStore
-        from .store import KnowledgeGraphStore
+        from .graph.store import KnowledgeGraphStore
 
         self.knowledge = KnowledgeGraphStore(
             self.db_path,

package/lattice_brain/ingestion.py

@@ -132,7 +132,7 @@ class IngestionPipeline:
     # ── public API ───────────────────────────────────────────────────────────
     def ingest(self, item: IngestionItem, *, user_email: Optional[str] = None) -> IngestionResult:
         """Normalize, hash, route through dispatch_tool, and record provenance."""
-        source_type = str(item.source_type or "text").strip()
+        source_type = str(item.source_type or "text").strip().lower()
         if not self.available():
             return IngestionResult(
                 status="unavailable", source_type=source_type,
@@ -187,25 +187,33 @@ class IngestionPipeline:
         embedded = bool(self._kg.node_is_embedded(node_id)) if node_id else False
         title = raw.get("title") or item.title
 
-        prov = self._kg.record_provenance(
-            node_id=node_id,
-            source_type=source_type,
-            pipeline=self._pipeline_name,
-            source_uri=item.source_uri,
-            content_hash=content_hash,
-            title=title,
-            owner=owner,
-            workspace_id=item.workspace_id,
-            captured_at=captured_at,
-            modified_at=item.modified_at,
-            embedded=embedded,
-            linked=bool(raw.get("source_node_id")),
-            duplicate=bool(raw.get("duplicate")),
-            agent_used=item.agent_used,
-            chunk_count=len(chunk_ids),
-            permissions=item.permissions,
-            metadata=item.metadata,
-        )
+        # Provenance capture must never turn an already-persisted ingest into a
+        # caller-visible failure: the graph write above succeeded, so a broken
+        # provenance table degrades the result instead of raising.
+        provenance_detail: Optional[str] = None
+        try:
+            prov = self._kg.record_provenance(
+                node_id=node_id,
+                source_type=source_type,
+                pipeline=self._pipeline_name,
+                source_uri=item.source_uri,
+                content_hash=content_hash,
+                title=title,
+                owner=owner,
+                workspace_id=item.workspace_id,
+                captured_at=captured_at,
+                modified_at=item.modified_at,
+                embedded=embedded,
+                linked=bool(raw.get("source_node_id")),
+                duplicate=bool(raw.get("duplicate")),
+                agent_used=item.agent_used,
+                chunk_count=len(chunk_ids),
+                permissions=item.permissions,
+                metadata=item.metadata,
+            )
+        except Exception as exc:  # noqa: BLE001 — the ingest itself already landed
+            prov = {}
+            provenance_detail = f"provenance capture failed: {exc}"
         if self._audit is not None:
             try:
                 self._audit(
@@ -232,11 +240,16 @@ class IngestionPipeline:
             embedded=embedded,
             indexing_status="indexed",
             provenance_id=prov.get("id"),
+            detail=provenance_detail,
         )
 
     # ── routing helpers ──────────────────────────────────────────────────────
     def _ingest_text(self, item, *, source_type, owner, captured_at) -> Dict[str, Any]:
         text = item.text or ""
+        if not text.strip():
+            raise ValueError(
+                f"Empty content: {source_type} ingestion requires non-empty text."
+            )
         if len(text.encode("utf-8", "ignore")) > self._max_text_bytes:
             raise ValueError(
                 f"Text payload exceeds the {self._max_text_bytes // (1024 * 1024)}MB ingestion limit."
@@ -297,6 +310,8 @@ class IngestionPipeline:
         path = Path(item.path)
         if not path.exists():
             raise FileNotFoundError(f"File not found: {path}")
+        if path.is_dir():
+            raise ValueError(f"File ingestion requires a file, got a directory: {path}")
         return self._kg.ingest_document(
             path,
             original_filename=item.title or path.name,

package/lattice_brain/runtime/agent_runtime.py

@@ -42,6 +42,7 @@ from .contracts import (
     contract_views,
     extract_contract,
     multi_agent_contract,
+    run_record_contract,
     runtime_boundary_contract,
 )
 
@@ -308,7 +309,7 @@ class AgentRuntime:
     def get_run(self, run_id: str, *, scope: Optional[str] = None) -> Dict[str, Any]:
         run = self._store.get_agent_run(run_id, workspace_id=scope)
         payload = {"run": run}
-        contract = extract_contract(run)
+        contract = self._ensure_contract(run)
         if contract is not None:
             payload["contract"] = contract_view(contract)
         return payload
@@ -324,7 +325,7 @@ class AgentRuntime:
     def events(self, run_id: str, *, scope: Optional[str] = None) -> Dict[str, Any]:
         run = self._store.get_agent_run(run_id, workspace_id=scope)
         status = str(run.get("status") or "")
-        contract = extract_contract(run)
+        contract = self._ensure_contract(run)
         return {
             "run_id": run_id,
             "status": status,
@@ -364,6 +365,35 @@ class AgentRuntime:
     def _clamp_retries(self, max_retries: int) -> int:
         return max(0, min(int(max_retries or 0), self._max_retries_cap))
 
+    def _validate_roles(self, roles: Optional[List[str]]) -> Optional[List[str]]:
+        """Reject unknown roles at the boundary instead of deep in orchestration.
+
+        ``preview`` reports unknown roles as a blocking reason; execution paths
+        must enforce the same contract so a run can never be recorded with a
+        role the runtime does not own.
+        """
+        if not roles:
+            return None
+        unknown = [role for role in roles if role not in AGENT_ROLES]
+        if unknown:
+            raise ValueError(f"unknown roles: {', '.join(unknown)}")
+        return list(roles)
+
+    @staticmethod
+    def _ensure_contract(record: Any) -> Optional[Dict[str, Any]]:
+        """Return the record's family contract, synthesizing one for legacy rows.
+
+        Every read surface (get_run/events/replay) must expose the
+        ``agent-run-contract/v1`` envelope even for runs persisted before the
+        contract family existed, so consumers never need a legacy branch.
+        """
+        contract = extract_contract(record)
+        if contract is not None:
+            return contract
+        if isinstance(record, dict) and record.get("id"):
+            return run_record_contract(record)
+        return None
+
     @staticmethod
     def _result_patch(result: Any, goal: str) -> Dict[str, Any]:
         return {
@@ -420,6 +450,7 @@ class AgentRuntime:
         """Create the durable queued row used by the async executor."""
         if not str(goal or "").strip():
             raise ValueError("goal is required")
+        roles = self._validate_roles(roles)
         pre_dispatch = self._fire_pre_run(
             goal=goal,
             roles=roles,
@@ -454,7 +485,9 @@ class AgentRuntime:
             execution_mode="async",
             requested_roles=roles or None,
             inputs=inputs or {},
-            max_retries=max_retries,
+            # Persist the clamped budget so the durable row reflects what the
+            # executor will actually honor, not the raw client request.
+            max_retries=self._clamp_retries(max_retries),
         )
         payload: Dict[str, Any] = {"run": run}
         if pre_dispatch is not None:
@@ -574,6 +607,7 @@ class AgentRuntime:
     ) -> Dict[str, Any]:
         if not str(goal or "").strip():
             raise ValueError("goal is required")
+        roles = self._validate_roles(roles)
 
         pre_dispatch = self._fire_pre_run(
             goal=goal,

package/lattice_brain/runtime/multi_agent.py

@@ -21,7 +21,7 @@ from typing import Any, Callable, Dict, List, Optional
 from .contracts import multi_agent_contract
 
 
-MULTI_AGENT_VERSION = "8.6.0"
+MULTI_AGENT_VERSION = "8.8.0"
 
 AGENT_ROLES = ("researcher", "planner", "executor", "reviewer", "release")
 CORE_PIPELINE = ("planner", "executor", "reviewer")

package/latticeai/__init__.py

@@ -1,3 +1,3 @@
 """Lattice AI - modular server package."""
 
-__version__ = "8.6.0"
+__version__ = "8.8.0"