ltcai 7.3.0 → 7.5.0

package/README.md

@@ -69,42 +69,42 @@ You need Lattice AI when:
 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/v7.0.0/screenshots/01-login.png)
+![Login](output/release/v7.5.0/screenshots/01-login.png)
 
 ### 2. Environment Analysis
 
 See what kind of local AI experience this computer can support before choosing a
 model.
 
-![Environment Analysis](output/release/v7.0.0/screenshots/02-environment-analysis.png)
+![Environment Analysis](output/release/v7.5.0/screenshots/02-environment-analysis.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/v7.0.0/screenshots/03-recommended-models.png)
+![Recommended Models](output/release/v7.5.0/screenshots/03-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/v7.0.0/screenshots/04-install-load-progress.png)
+![Install and Load](output/release/v7.5.0/screenshots/04-install-load-progress.png)
 
 ### 5. Brain Chat
 
 Talk normally. Useful decisions and context become memory, then appear later as
 topics, relationships, and graph structure.
 
-![Brain Chat Home](output/release/v7.0.0/screenshots/05-brain-chat-home.png)
+![Brain Chat Home](output/release/v7.5.0/screenshots/05-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/v7.0.0/screenshots/13-review-center.png)
+![Review Center](output/release/v7.5.0/screenshots/13-review-center.png)
 
 ## Brain Depths
 
@@ -120,10 +120,10 @@ The user travels inward from everyday memory to deeper structure:
 
 Walkthrough:
 
-![v7.0.0 Living Brain walkthrough](output/release/v7.0.0/gifs/v7.0.0-living-brain-walkthrough.gif)
+![v7.5.0 Living Brain walkthrough](output/release/v7.5.0/gifs/v7.5.0-living-brain-walkthrough.gif)
 
 Screenshot index and capture notes:
-[output/release/v7.0.0/SCREENSHOT_INDEX.md](output/release/v7.0.0/SCREENSHOT_INDEX.md)
+[output/release/v7.5.0/SCREENSHOT_INDEX.md](output/release/v7.5.0/SCREENSHOT_INDEX.md)
 
 ## Install
 
@@ -200,32 +200,34 @@ See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for developer workflow details.
 
 ## Current Release
 
-The current release is **7.3.0 Runtime Contract & Retrieval Quality**:
-
-- Single-agent and multi-agent execution now share a serializable
-  `agent-run-contract/v1` payload for run identity, mode, status, roles,
-  timeline, retries, artifacts, and terminal state.
-- Agent runtime API responses include the shared contract, keeping real and
-  simulated run history distinguishable as runtime extraction continues.
-- Brain quality evaluation now includes deterministic hybrid recall/ranking
-  regression thresholds, not only "some recall exists" checks.
-- The 7.2.0 preview/diagnostics work remains the admin trust surface while
-  7.3.0 tightens the underlying run and retrieval contracts.
-- The roadmap focus is durability over model choice: knowledge, run evidence,
-  and retrieval quality become measurable product assets.
-
-Expected artifacts for 7.3.0 release must use exact filenames:
-
-- `dist/ltcai-7.3.0-py3-none-any.whl`
-- `dist/ltcai-7.3.0.tar.gz`
-- `ltcai-7.3.0.tgz`
-- `dist/ltcai-7.3.0.vsix`
-- `src-tauri/target/release/bundle/dmg/Lattice AI_7.3.0_aarch64.dmg`
+The current release is **7.5.0 Runtime Debt Burn-down & Release Risk Cleanup**:
+
+- Agent runs, workflow runs, audit events, and realtime events now carry the
+  `agent-run-contract/v1` family envelope, so replay, admin review, and live
+  feeds can inspect run identity, runtime, status, timeline, and artifacts
+  through one contract shape.
+- AgentRuntime and realtime API responses now expose compact `contracts` views
+  so downstream consumers can read the common envelope instead of re-parsing
+  surface-specific records.
+- Brain quality evaluation now runs a real KnowledgeGraphStore + SearchService
+  corpus fixture with 250+ records, judged queries, recall, precision, NDCG,
+  and must-include hit-rate thresholds.
+- Release risk cleanup removes stale-artifact upload ambiguity, clears npm audit
+  findings, and updates the Tauri 2 stack so the old `block v0.1.6`
+  future-incompatibility warning is gone.
+
+Expected artifacts for 7.5.0 release must use exact filenames:
+
+- `dist/ltcai-7.5.0-py3-none-any.whl`
+- `dist/ltcai-7.5.0.tar.gz`
+- `ltcai-7.5.0.tgz`
+- `dist/ltcai-7.5.0.vsix`
+- `src-tauri/target/release/bundle/dmg/Lattice AI_7.5.0_aarch64.dmg`
 
 Do not upload `dist/*`. Package registry publishing remains owner-run.
 
 See [docs/ROADMAP_RECOMMENDATIONS.md](docs/ROADMAP_RECOMMENDATIONS.md) for the
-strategic roadmap slice applied in 7.3.0 and the follow-up tracks.
+strategic roadmap slices applied through 7.5.0 and the follow-up tracks.
 
 ## Known Limitations
 
@@ -242,6 +244,8 @@ strategic roadmap slice applied in 7.3.0 and the follow-up tracks.
 
 | Version | Theme |
 | --- | --- |
+| 7.5.0 | Runtime Debt Burn-down & Release Risk Cleanup: API consumers get normalized contract views, retrieval quality uses a 250+ record corpus fixture, stale artifact risk is removed, npm audit is clean, and Tauri is updated past the old block warning |
+| 7.4.0 | Runtime Contract Convergence & Corpus Retrieval: agent/workflow/audit/realtime records share the agent-run-contract/v1 family, and retrieval quality gates run against a real corpus-scale fixture |
 | 7.3.0 | Runtime Contract & Retrieval Quality: shared agent-run contract across runtimes plus deterministic hybrid recall/ranking regression gates |
 | 7.2.0 | Runtime Trust Baseline: agent run preview/readiness, simulation-mode guardrails, live ToolRegistry manifest/diagnostics, and tests for dispatch/governance/catalog drift |
 | 7.1.0 | Brain Usability Completion: clearer first-run onboarding, ingestion progress/emergence, richer graph controls, inline answer proof, workspace/profile/admin discovery, empty/error/consent feedback, and VS Code sync status |

package/docs/CHANGELOG.md

@@ -4,6 +4,56 @@ 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.
 
+## [7.5.0] - 2026-06-20
+
+> Runtime Debt Burn-down & Release Risk Cleanup. Turns the 7.4.0 contract
+> envelope into a consumed API surface, expands retrieval quality to a 250+
+> record local corpus fixture, and removes release/security warnings.
+
+### Added
+- `extract_contract`, `require_contract`, `contract_view`, and `contract_views`
+  helpers for consumers that need a surface-agnostic `agent-run-contract/v1`
+  projection.
+- AgentRuntime status/list/detail/events and realtime feed responses now expose
+  compact `contracts` views alongside legacy payloads.
+- Deterministic 250+ record retrieval benchmark corpus while keeping 12 judged
+  queries and real `KnowledgeGraphStore` + `SearchService` execution.
+- Refreshed README release evidence screenshots and walkthrough GIF under
+  `output/release/v7.5.0/`.
+
+### Changed
+- Tauri Rust/CLI dependencies are updated within the Tauri 2 line, removing the
+  old transitive `block v0.1.6` future-incompatibility warning.
+- npm dependency overrides move `js-yaml` to a non-vulnerable version; `npm
+  audit` reports 0 vulnerabilities.
+- CI lint compatibility is restored for the Brain quality gate script.
+- Package/runtime/static metadata is synchronized to 7.5.0; package publish and
+  deployment remain owner-run only.
+
+## [7.4.0] - 2026-06-20
+
+> Runtime Contract Convergence & Corpus Retrieval. Completes the
+> agent-run-contract/v1 family across run storage, workflow execution, audit
+> events, realtime events, and a real corpus-scale retrieval quality gate.
+
+### Added
+- Persisted agent and workflow run rows now carry refreshed contract metadata
+  for queued, running, terminal, cancelled, and interrupted states.
+- Workflow engine results, replay payloads, audit log events, and realtime SSE
+  feed events now expose the same `agent-run-contract/v1` family envelope while
+  preserving existing top-level compatibility fields.
+- Corpus-scale retrieval fixture with 30+ documents, judged queries,
+  must-include expectations, and thresholds for recall, precision, NDCG, and
+  hit rate.
+- `scripts/brain_quality_eval.py` now exercises the real local
+  `KnowledgeGraphStore` + `SearchService` hybrid retrieval path before scoring.
+
+### Changed
+- `RetrievalBenchmarkRunner` reports dynamic metric aliases for the selected
+  `top_k` and a `must_include_hit_rate`.
+- Package/runtime/static metadata is synchronized to 7.4.0; package publish and
+  deployment remain owner-run only.
+
 ## [7.3.0] - 2026-06-20
 
 > Runtime Contract & Retrieval Quality. Turns the next AgentRuntime extraction

package/docs/ROADMAP_RECOMMENDATIONS.md

@@ -16,12 +16,38 @@ small release-sized work. The operating principle stays unchanged:
 - Security and trust: run contracts distinguish runtime type and execution mode
   so simulated output is not presented as real execution.
 
+## 7.4.0 Applied Slice
+
+7.4.0 completes the next roadmap slice without deferring it:
+
+- Runtime convergence: agent runs, workflow runs, audit events, and realtime
+  events all expose the `agent-run-contract/v1` family envelope while keeping
+  legacy top-level fields for compatibility.
+- Trust and operations: persisted run rows refresh their contract through
+  queued, running, terminal, cancelled, and interrupted states; audit events are
+  contracted only after secret redaction.
+- Retrieval quality and scale: the CI quality gate now seeds a real local
+  Knowledge Graph corpus and scores SearchService hybrid retrieval with judged
+  queries, recall, precision, NDCG, and must-include hit-rate thresholds.
+
+## 7.5.0 Applied Slice
+
+7.5.0 burns down the remaining 7.4.0 risk instead of deferring it:
+
+- Contract consumption: AgentRuntime and realtime feed APIs now emit compact
+  `contracts` views so UI, replay, admin, and export consumers can depend on the
+  shared family envelope directly.
+- Retrieval scale: the corpus fixture now runs against 250+ local records while
+  keeping judged queries, graded relevance, and must-include expectations.
+- Release trust: stale artifact mixing is handled through clean exact-version
+  artifact generation, npm audit findings are cleared, and the Tauri 2 stack is
+  updated past the old `block v0.1.6` future-incompatibility warning.
+
 ## Near-Term Tracks
 
 1. Retrieval quality and scale
-   - Expand fixture datasets for hybrid search.
-   - Add latency budgets for large corpora.
-   - Track recall, precision, and ranking regressions in CI.
+   - Add latency budgets for larger corpora.
+   - Track per-channel keyword/vector/graph diagnostics in CI.
    - Tune semantic/graph/keyword fusion by query class.
 
 2. Incremental ingestion
@@ -30,8 +56,8 @@ small release-sized work. The operating principle stays unchanged:
    - Surface conflict resolution for contradictory memories.
 
 3. Runtime convergence
-   - Use `agent-run-contract/v1` across single-agent, multi-agent, workflows,
-     audit logs, and UI event streams.
+   - Migrate remaining UI run/replay/admin components to read the API-level
+     compact contract views as their primary source.
    - Keep simulation mode explicit and never record it as product success.
    - Route tools through explicit registry/governance contracts.
 

package/lattice_brain/__init__.py

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

package/lattice_brain/quality.py

@@ -285,6 +285,18 @@ class StructuredContextAssembler:
 # -----------------------------
 # 6. Retrieval Benchmark Fixture Runner
 # -----------------------------
+def _relevance_grades(relevant: Any) -> Dict[str, float]:
+    """Normalize a ``relevant`` spec into a ``{doc_id: grade}`` map.
+
+    Accepts a graded dict (``{"doc": 3}``) or a binary list/set/tuple (grade 1
+    for every id), so judged fixtures can express graded relevance for nDCG
+    while older binary fixtures keep working unchanged.
+    """
+    if isinstance(relevant, dict):
+        return {str(k): float(v) for k, v in relevant.items()}
+    return {str(doc_id): 1.0 for doc_id in (relevant or [])}
+
+
 class RetrievalBenchmarkRunner:
     def __init__(self):
         self.results: List[Dict] = []
@@ -297,25 +309,36 @@ class RetrievalBenchmarkRunner:
             precisions = []
             ndcgs = []
             for query in judged:
-                relevant = set(query.get("relevant") or [])
+                grades = _relevance_grades(query.get("relevant"))
+                relevant = set(grades)
                 retrieved = list(query.get("retrieved") or [])[:top_k]
                 if not relevant:
                     continue
                 hits = [doc_id for doc_id in retrieved if doc_id in relevant]
                 recalls.append(len(hits) / len(relevant))
                 precisions.append(len(hits) / max(1, len(retrieved)))
+                # Graded DCG: each retrieved doc contributes its relevance grade
+                # discounted by log2(rank + 2). IDCG ranks the highest grades
+                # first, so nDCG rewards putting the *most* relevant docs on top.
+                # Binary fixtures fall back to grade 1 via _relevance_grades.
                 dcg = sum(
-                    1.0 / math.log2(rank + 2)
+                    grades.get(doc_id, 0.0) / math.log2(rank + 2)
                     for rank, doc_id in enumerate(retrieved)
-                    if doc_id in relevant
                 )
-                ideal = sum(1.0 / math.log2(rank + 2) for rank in range(min(len(relevant), top_k)))
+                ideal_grades = sorted(grades.values(), reverse=True)[:top_k]
+                ideal = sum(g / math.log2(rank + 2) for rank, g in enumerate(ideal_grades))
                 ndcgs.append(dcg / ideal if ideal else 0.0)
             recall = sum(recalls) / len(recalls) if recalls else 0.0
             precision = sum(precisions) / len(precisions) if precisions else 0.0
             ndcg = sum(ndcgs) / len(ndcgs) if ndcgs else 0.0
         else:
             recall = precision = ndcg = 0.0
+        must_include = [
+            bool(set(query.get("must_include") or []).intersection(set(list(query.get("retrieved") or [])[:top_k])))
+            for query in judged
+            if query.get("must_include")
+        ]
+        must_include_hit_rate = sum(1 for hit in must_include if hit) / len(must_include) if must_include else 1.0
         metrics = {
             "fixture": fixture_name,
             "queries": len(queries),
@@ -323,6 +346,10 @@ class RetrievalBenchmarkRunner:
             "recall@5": round(recall, 4),
             "precision@5": round(precision, 4),
             "ndcg@5": round(ndcg, 4),
+            f"recall@{top_k}": round(recall, 4),
+            f"precision@{top_k}": round(precision, 4),
+            f"ndcg@{top_k}": round(ndcg, 4),
+            "must_include_hit_rate": round(must_include_hit_rate, 4),
             "top_k": top_k,
             "judged": len(judged),
         }

package/lattice_brain/retrieval_benchmark_fixtures.py

@@ -0,0 +1,92 @@
+"""Corpus-scale retrieval fixture for the 7.5.0 Brain quality gate."""
+
+from __future__ import annotations
+
+FIXTURE_NAME = "7.5.0-corpus-scale-hybrid-retrieval"
+TOP_K = 5
+
+CORE_DOCUMENTS = [
+    {"id": "doc:agent-runtime-contract", "type": "Decision", "title": "Agent runtime contract", "content": "Workflow run, agent run, audit event, and realtime event records must carry the agent-run-contract/v1 family envelope with run id, runtime, status, timeline, and artifacts."},
+    {"id": "doc:workflow-observability", "type": "Document", "title": "Workflow observability", "content": "Workflow Designer persists queued, running, awaiting approval, cancelled, interrupted, partial, failed, and ok runs with replayable timeline events."},
+    {"id": "doc:audit-trust", "type": "Security", "title": "Audit trust", "content": "Audit events are append-only, redacted before persistence, and linked to execution contracts for admin review without leaking secrets."},
+    {"id": "doc:realtime-feed", "type": "Document", "title": "Realtime execution feed", "content": "The realtime SSE bus publishes workspace, agent, workflow, and execution events with workspace scope, event type, payload, sequence, and contract metadata."},
+    {"id": "doc:retrieval-benchmark", "type": "Benchmark", "title": "Retrieval benchmark strategy", "content": "Hybrid retrieval quality must be checked with corpus-scale fixtures, judged queries, recall, precision, ndcg, and must-include hit rate."},
+    {"id": "doc:hybrid-search", "type": "Architecture", "title": "Hybrid search", "content": "SearchService fuses keyword, vector, and graph retrieval channels with weighted scores and scoped workspace filtering."},
+    {"id": "doc:knowledge-graph", "type": "Architecture", "title": "Knowledge graph stabilization", "content": "The Knowledge Graph preserves legacy read compatibility, non-destructive migrations, vector indexing, relationship traversal, and provenance."},
+    {"id": "doc:local-first", "type": "Strategy", "title": "Local-first product wedge", "content": "Lattice AI is local-first: durable knowledge, private workspace memory, local LLM routing, and model-independent context are the product wedge."},
+    {"id": "doc:brain-proof", "type": "UX", "title": "Brain proof and citations", "content": "Brain proof shows durable recall, source citation, graph counts, vector counts, and model continuity evidence in chat."},
+    {"id": "doc:onboarding", "type": "UX", "title": "Five minute onboarding loop", "content": "The first loop asks users to add a source, ask a question, see Brain proof, and understand expected installation time."},
+    {"id": "doc:vscode-sync", "type": "Integration", "title": "VS Code extension state", "content": "VS Code extension integration shows app connection state, indexing status, command routing, and extension-to-app sync health."},
+    {"id": "doc:workspace-admin", "type": "Workspace", "title": "Workspace profile admin discovery", "content": "Personal workspace, organization workspace, profile, admin, members, roles, permissions, and security surfaces must be discoverable."},
+    {"id": "doc:empty-error-consent", "type": "UX", "title": "Empty error consent states", "content": "Empty states, error states, consent prompts, retries, and privacy feedback should be explicit across ingestion, graph, chat, and workspace flows."},
+    {"id": "doc:tool-registry", "type": "Architecture", "title": "Tool registry separation", "content": "ToolRegistry separates tool definitions, permissions, dispatch, audit, and UI discovery from AgentRuntime orchestration."},
+    {"id": "doc:config-centralization", "type": "Architecture", "title": "Config centralization", "content": "Configuration should be centralized into explicit objects instead of hidden globals so runtime, tests, and packaging are predictable."},
+    {"id": "doc:server-decomposition", "type": "Architecture", "title": "Server decomposition", "content": "Server decomposition moves routers, services, runtime context, and persistence seams into focused modules with dependency injection."},
+    {"id": "doc:incremental-ingestion", "type": "Pipeline", "title": "Incremental ingestion", "content": "Background indexing needs duplicate detection, conflict resolution, incremental updates, and merge behavior for large personal corpora."},
+    {"id": "doc:vector-index-evolution", "type": "Pipeline", "title": "Vector index evolution", "content": "sqlite-vec migration, HNSW evaluation, query caching, embedding caching, and retrieval caching support larger corpora."},
+    {"id": "doc:security-zero-trust", "type": "Security", "title": "Zero trust defaults", "content": "Zero-trust defaults include audit logging, secret redaction, dependency vulnerability monitoring, and automated security scanning."},
+    {"id": "doc:agentic-hitl", "type": "Workflow", "title": "Agentic human review", "content": "Agentic workflows need human-in-the-loop review, approval gates, rollback paths, review queues, and auditable decisions."},
+    {"id": "doc:temporal-reasoning", "type": "Brain", "title": "Temporal reasoning", "content": "Temporal graph states, historical memory, contradiction detection, synthesis, and recommendations make the Brain proactive."},
+    {"id": "doc:multimodal-memory", "type": "Brain", "title": "Multimodal memory", "content": "Images, audio, video, documents, and chat should ingest into one durable Brain with retrieval and citation proof."},
+    {"id": "doc:developer-api", "type": "API", "title": "Developer API", "content": "A secure developer API exposes third-party access to workspace knowledge, tools, runs, contracts, and audit trails."},
+    {"id": "doc:team-brains", "type": "Business", "title": "Team Brains", "content": "Team Brains, encrypted sharing, premium cloud sync, hosted models, plugin marketplace, and public benchmarks support monetization."},
+    {"id": "doc:docker-tauri", "type": "Deployment", "title": "Deployment operations", "content": "Docker Compose deployment, one-click installation, Tauri auto-updates, rollback support, and exact release artifacts improve operations."},
+    {"id": "doc:model-routing", "type": "Runtime", "title": "Model orchestration", "content": "Ollama, LM Studio, MLX, and cloud models need automatic fallback, routing, and replaceable model boundaries."},
+    {"id": "doc:strict-quality", "type": "Quality", "title": "Strict code quality", "content": "Async-first architecture, dependency injection, centralized exceptions, mypy or pyright, TypeScript strict mode, E2E tests, and property tests reduce regressions."},
+    {"id": "distractor:theme-editor", "type": "Distractor", "title": "Theme editor", "content": "Color palettes, typography, and sidebar icon sizing are useful visual polish topics."},
+    {"id": "distractor:calendar", "type": "Distractor", "title": "Calendar reminders", "content": "Calendar reminders and meeting agenda formatting are productivity integrations."},
+    {"id": "distractor:billing", "type": "Distractor", "title": "Billing invoices", "content": "Invoices, payment receipts, and subscription emails can be stored but are not the Brain quality gate."},
+    {"id": "distractor:mobile-shell", "type": "Distractor", "title": "Mobile shell", "content": "A mobile companion can improve access with push notifications and offline cache."},
+    {"id": "distractor:marketing", "type": "Distractor", "title": "Marketing landing page", "content": "Landing pages and hero copy shape positioning and campaign messaging."},
+]
+
+_DISTRACTOR_TOPICS = [
+    ("finance", "quarterly planning", "budget variance vendor renewal procurement forecast"),
+    ("design", "component polish", "spacing typography icon density color token accessibility"),
+    ("support", "customer escalation", "ticket triage priority response macro satisfaction"),
+    ("ops", "incident rotation", "oncall handoff status page maintenance window"),
+    ("sales", "pipeline review", "lead scoring opportunity stage forecast account"),
+    ("calendar", "meeting schedule", "agenda reminder availability invite followup"),
+    ("email", "inbox policy", "thread label archive template unsubscribe"),
+    ("mobile", "companion shell", "push notification offline cache deep link"),
+    ("billing", "invoice lifecycle", "receipt tax subscription entitlement payment"),
+    ("analytics", "dashboard report", "cohort funnel metric annotation export"),
+    ("theme", "appearance settings", "palette contrast sidebar density motion"),
+    ("legal", "compliance packet", "clause obligation renewal signature counterparty"),
+]
+
+
+def _generated_distractors() -> list[dict[str, str]]:
+    """Create a deterministic local corpus large enough to exercise ranking."""
+    docs: list[dict[str, str]] = []
+    for batch in range(20):
+        for topic, title, terms in _DISTRACTOR_TOPICS:
+            docs.append({
+                "id": f"distractor:{topic}:{batch:02d}",
+                "type": "Distractor",
+                "title": f"{title.title()} {batch + 1}",
+                "content": (
+                    f"{title} note {batch + 1}. This record discusses {terms}. "
+                    "It is intentionally unrelated to the judged Brain quality topics "
+                    "and exists to make local ranking tests compete against realistic noise."
+                ),
+            })
+    return docs
+
+
+DOCUMENTS = CORE_DOCUMENTS + _generated_distractors()
+
+QUERIES = [
+    {"query": "agent workflow audit realtime contract run status timeline", "relevant": {"doc:agent-runtime-contract": 3, "doc:workflow-observability": 2, "doc:audit-trust": 2, "doc:realtime-feed": 2}, "must_include": ["doc:agent-runtime-contract"]},
+    {"query": "workflow queued running cancelled interrupted replay approval", "relevant": {"doc:workflow-observability": 3, "doc:agentic-hitl": 2}, "must_include": ["doc:workflow-observability"]},
+    {"query": "audit log redacted secrets admin review contract", "relevant": {"doc:audit-trust": 3}, "must_include": ["doc:audit-trust"]},
+    {"query": "SSE realtime workspace event payload sequence contract", "relevant": {"doc:realtime-feed": 3, "doc:agent-runtime-contract": 2}, "must_include": ["doc:realtime-feed"]},
+    {"query": "hybrid retrieval keyword vector graph weighted scoped search", "relevant": {"doc:hybrid-search": 3, "doc:knowledge-graph": 2, "doc:retrieval-benchmark": 2}, "must_include": ["doc:hybrid-search"]},
+    {"query": "corpus scale recall precision ndcg judged queries", "relevant": {"doc:retrieval-benchmark": 3}, "must_include": ["doc:retrieval-benchmark"]},
+    {"query": "local first model independent durable memory brain proof citation", "relevant": {"doc:local-first": 3, "doc:brain-proof": 2}, "must_include": ["doc:local-first"]},
+    {"query": "incremental indexing duplicate conflict merge background ingestion", "relevant": {"doc:incremental-ingestion": 3}, "must_include": ["doc:incremental-ingestion"]},
+    {"query": "workspace admin profile organization members roles permissions", "relevant": {"doc:workspace-admin": 3}, "must_include": ["doc:workspace-admin"]},
+    {"query": "tool registry separation dependency injection runtime context", "relevant": {"doc:tool-registry": 3, "doc:server-decomposition": 2, "doc:config-centralization": 2}, "must_include": ["doc:tool-registry"]},
+    {"query": "human in the loop approval review queue rollback", "relevant": {"doc:agentic-hitl": 3}, "must_include": ["doc:agentic-hitl"]},
+    {"query": "model routing ollama lm studio mlx cloud fallback replaceable", "relevant": {"doc:model-routing": 3, "doc:local-first": 2}, "must_include": ["doc:model-routing"]},
+]

package/lattice_brain/runtime/agent_runtime.py

@@ -37,7 +37,7 @@ from .multi_agent import (
     MULTI_AGENT_VERSION,
     ROLE_AGENT_IDS,
 )
-from .contracts import multi_agent_contract
+from .contracts import contract_view, contract_views, extract_contract, multi_agent_contract
 
 ROLE_DESCRIPTIONS = {
     "researcher": "Gathers workspace context and memory for the goal.",
@@ -227,6 +227,7 @@ class AgentRuntime:
             "roles": self.roles(),
             "agents": self._roster(runs),
             "runs": runs[:25],
+            "contracts": contract_views(runs[:25]),
         }
 
     def preview(
@@ -282,13 +283,27 @@ class AgentRuntime:
 
     # ── events / state ────────────────────────────────────────────────────
     def list_runs(self, *, scope: Optional[str] = None) -> Dict[str, Any]:
-        return self._store.list_agents(workspace_id=scope)
+        listing = self._store.list_agents(workspace_id=scope)
+        runs = list(listing.get("runs") or [])
+        payload = dict(listing)
+        payload["contracts"] = contract_views(runs)
+        return payload
 
     def get_run(self, run_id: str, *, scope: Optional[str] = None) -> Dict[str, Any]:
-        return {"run": self._store.get_agent_run(run_id, workspace_id=scope)}
+        run = self._store.get_agent_run(run_id, workspace_id=scope)
+        payload = {"run": run}
+        contract = extract_contract(run)
+        if contract is not None:
+            payload["contract"] = contract_view(contract)
+        return payload
 
     def replay(self, run_id: str, *, scope: Optional[str] = None) -> Dict[str, Any]:
-        return {"replay": self._store.replay_agent_run(run_id, workspace_id=scope)}
+        replay = self._store.replay_agent_run(run_id, workspace_id=scope)
+        payload = {"replay": replay}
+        contract = extract_contract(replay)
+        if contract is not None:
+            payload["contract"] = contract_view(contract)
+        return payload
 
     def events(self, run_id: str, *, scope: Optional[str] = None) -> Dict[str, Any]:
         run = self._store.get_agent_run(run_id, workspace_id=scope)
@@ -300,6 +315,7 @@ class AgentRuntime:
             "current_role": run.get("current_role"),
             "timeline": run.get("timeline") or [],
             "handoffs": run.get("handoffs") or [],
+            "contract": contract_view(run),
         }
 
     # ── execution ─────────────────────────────────────────────────────────