ltcai 7.3.0 → 7.4.0

package/README.md

@@ -200,32 +200,33 @@ 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.4.0 Runtime Contract Convergence & Corpus Retrieval**:
+
+- 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.
+- Persisted queued/running/terminal agent and workflow rows refresh their
+  contract on every state transition, including cancellation and interruption.
+- Audit rows keep their existing admin fields while adding redacted contract
+  metadata; realtime SSE events keep `area`, `event_type`, `workspace_id`, and
+  `payload` while adding the same contract family.
+- Brain quality evaluation now runs a real KnowledgeGraphStore + SearchService
+  corpus fixture with judged queries, recall, precision, NDCG, and must-include
+  hit-rate thresholds.
+
+Expected artifacts for 7.4.0 release must use exact filenames:
+
+- `dist/ltcai-7.4.0-py3-none-any.whl`
+- `dist/ltcai-7.4.0.tar.gz`
+- `ltcai-7.4.0.tgz`
+- `dist/ltcai-7.4.0.vsix`
+- `src-tauri/target/release/bundle/dmg/Lattice AI_7.4.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.4.0 and the follow-up tracks.
 
 ## Known Limitations
 
@@ -242,6 +243,7 @@ strategic roadmap slice applied in 7.3.0 and the follow-up tracks.
 
 | Version | Theme |
 | --- | --- |
+| 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,30 @@ 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.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,25 @@ 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.
+
 ## 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 +43,7 @@ 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.
+   - Drive UI run/replay/admin views from the shared contract family.
    - 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.4.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,56 @@
+"""Corpus-scale retrieval fixture for the 7.4.0 Brain quality gate."""
+
+from __future__ import annotations
+
+FIXTURE_NAME = "7.4.0-corpus-scale-hybrid-retrieval"
+TOP_K = 5
+
+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 but unrelated to retrieval contract benchmarks."},
+    {"id": "distractor:calendar", "type": "Distractor", "title": "Calendar reminders", "content": "Calendar reminders and meeting agenda formatting are integrations but not the runtime event contract path."},
+    {"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 but should not replace local-first desktop retrieval and run observability."},
+    {"id": "distractor:marketing", "type": "Distractor", "title": "Marketing landing page", "content": "Landing pages and hero copy do not prove durable knowledge or agent runtime correctness."},
+]
+
+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, "doc:security-zero-trust": 2}, "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, "doc:hybrid-search": 2}, "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, "doc:vector-index-evolution": 2}, "must_include": ["doc:incremental-ingestion"]},
+    {"query": "workspace admin profile organization members roles permissions", "relevant": {"doc:workspace-admin": 3, "doc:security-zero-trust": 2}, "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, "doc:workflow-observability": 2}, "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/contracts.py

@@ -4,6 +4,26 @@ These contracts are deliberately small and serializable.  The single-agent
 state machine and the multi-agent facade can evolve independently, but callers
 should see the same run identity, mode, status, role, timeline and artifact
 shape across both paths.
+
+Contract family (7.4.0)
+-----------------------
+Four observability surfaces — agent runs, workflow runs, audit events, and
+realtime events — now share one **contract family**, ``agent-run-contract/v1``.
+Every record emitted by any of these surfaces carries the same envelope keys so
+a single consumer (timeline UI, exporter, replay tooling) can treat them
+uniformly:
+
+* ``family``         — always :data:`CONTRACT_FAMILY` (``agent-run-contract/v1``).
+* ``schema_version`` — the per-surface schema string (see ``*_SCHEMA`` below).
+* ``kind``           — one of :data:`CONTRACT_KINDS`.
+* ``id``             — the record identity (run id / event id), may be ``None``.
+* ``status``         — a normalized lifecycle status string.
+* ``timestamp``      — ISO-8601 second-precision emit/observe time.
+
+Each surface keeps its own rich, surface-specific keys *in addition* to the
+envelope — the envelope is purely additive, so existing consumers are never
+broken.  :func:`stamp_contract` is the single place that writes the envelope;
+:func:`is_contract_member` validates membership for tests and importers.
 """
 
 from __future__ import annotations
@@ -17,6 +37,71 @@ def runtime_timestamp() -> str:
     return datetime.now().isoformat(timespec="seconds")
 
 
+# ── Contract family identity ────────────────────────────────────────────────
+# A single family string ties every observability surface together. Per-surface
+# schema versions live *under* the family so each surface can rev independently
+# without forking the family contract consumers depend on.
+CONTRACT_FAMILY = "agent-run-contract/v1"
+
+AGENT_RUN_SCHEMA = "agent-run-contract/v1"
+WORKFLOW_RUN_SCHEMA = "workflow-run-contract/v1"
+AUDIT_EVENT_SCHEMA = "audit-event-contract/v1"
+REALTIME_EVENT_SCHEMA = "realtime-event-contract/v1"
+
+CONTRACT_KINDS = ("agent_run", "workflow_run", "audit_event", "realtime_event")
+
+# The envelope keys every family member is guaranteed to expose.
+CONTRACT_ENVELOPE_KEYS = ("family", "schema_version", "kind", "id", "status", "timestamp")
+
+_SCHEMA_FOR_KIND = {
+    "agent_run": AGENT_RUN_SCHEMA,
+    "workflow_run": WORKFLOW_RUN_SCHEMA,
+    "audit_event": AUDIT_EVENT_SCHEMA,
+    "realtime_event": REALTIME_EVENT_SCHEMA,
+}
+
+
+def stamp_contract(
+    body: Dict[str, Any],
+    *,
+    kind: str,
+    identity: Optional[str],
+    status: str,
+    timestamp: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Return ``body`` with the ``agent-run-contract/v1`` envelope merged in.
+
+    Additive and idempotent: existing keys in ``body`` win for everything except
+    the six envelope keys, which are authoritative. ``kind`` must be one of
+    :data:`CONTRACT_KINDS`; the schema version is derived from it so callers
+    cannot mismatch ``kind`` and ``schema_version``.
+    """
+    if kind not in _SCHEMA_FOR_KIND:
+        raise ValueError(f"unknown contract kind: {kind!r}")
+    enveloped = dict(body)
+    enveloped["family"] = CONTRACT_FAMILY
+    enveloped["schema_version"] = _SCHEMA_FOR_KIND[kind]
+    enveloped["kind"] = kind
+    enveloped["id"] = identity
+    enveloped["status"] = status
+    enveloped["timestamp"] = timestamp or body.get("timestamp") or runtime_timestamp()
+    return enveloped
+
+
+def is_contract_member(record: Any) -> bool:
+    """True if ``record`` carries a valid ``agent-run-contract/v1`` envelope."""
+    if not isinstance(record, dict):
+        return False
+    if record.get("family") != CONTRACT_FAMILY:
+        return False
+    kind = record.get("kind")
+    if kind not in _SCHEMA_FOR_KIND:
+        return False
+    if record.get("schema_version") != _SCHEMA_FOR_KIND[kind]:
+        return False
+    return all(key in record for key in CONTRACT_ENVELOPE_KEYS)
+
+
 @dataclass(frozen=True)
 class AgentRunContract:
     run_id: Optional[str]
@@ -38,13 +123,11 @@ class AgentRunContract:
         return self.status in {"ok", "retried_ok", "failed", "rejected", "cancelled", "interrupted", "partial", "done"}
 
     def as_dict(self) -> Dict[str, Any]:
-        return {
-            "schema_version": self.schema_version,
+        body = {
             "run_id": self.run_id,
             "agent_id": self.agent_id,
             "runtime": self.runtime,
             "mode": self.mode,
-            "status": self.status,
             "goal": self.goal,
             "roles": list(self.roles),
             "current_role": self.current_role,
@@ -54,6 +137,12 @@ class AgentRunContract:
             "blocking_reasons": list(self.blocking_reasons),
             "is_terminal": self.is_terminal,
         }
+        return stamp_contract(
+            body,
+            kind="agent_run",
+            identity=self.run_id,
+            status=self.status,
+        )
 
 
 def multi_agent_contract(
@@ -80,6 +169,41 @@ def multi_agent_contract(
     ).as_dict()
 
 
+def run_record_contract(run: Dict[str, Any], *, runtime: str = "multi_agent") -> Dict[str, Any]:
+    """Build the family contract from a persisted agent run row."""
+    run = dict(run or {})
+    timeline = list(run.get("timeline") or [])
+    retry_history = list(run.get("retry_history") or [])
+    roles = list(run.get("roles_run") or run.get("requested_roles") or [])
+    if not roles:
+        roles = [
+            str(item.get("role"))
+            for item in timeline
+            if isinstance(item, dict) and item.get("role")
+        ]
+    return AgentRunContract(
+        run_id=run.get("id") or run.get("run_id"),
+        agent_id=str(run.get("agent_id") or "agent:executor"),
+        runtime=runtime,
+        mode=str(run.get("mode") or "simulation"),
+        status=str(run.get("status") or "unknown"),
+        goal=str(run.get("input") or run.get("goal") or ""),
+        roles=roles,
+        current_role=run.get("current_role"),
+        retries=len(retry_history),
+        timeline=timeline,
+        artifacts=[
+            {
+                "type": "run_record",
+                "workspace_id": run.get("workspace_id"),
+                "graph_node_id": run.get("graph_node_id"),
+                "execution_mode": run.get("execution_mode"),
+            }
+        ],
+        blocking_reasons=[str(run.get("error"))] if run.get("error") else [],
+    ).as_dict()
+
+
 def single_agent_contract(
     *,
     ctx: Any,
@@ -105,3 +229,114 @@ def single_agent_contract(
         artifacts=[],
         blocking_reasons=list(blocking_reasons or []),
     ).as_dict()
+
+
+# ── Sibling-surface contract builders ───────────────────────────────────────
+# These wrap the other three observability surfaces into the same family so a
+# consumer can iterate agent runs, workflow runs, audit events and realtime
+# events through one envelope.
+
+def workflow_run_contract(run: Any) -> Dict[str, Any]:
+    """Wrap a workflow run dict (``WorkflowRun.as_dict()``) in the family envelope.
+
+    Accepts either a ``WorkflowRun`` instance or its serialized dict so the
+    engine can stamp without importing the dataclass here (avoids a cycle).
+    """
+    body = run.as_dict() if hasattr(run, "as_dict") else dict(run or {})
+    run_id = body.get("id") or body.get("run_id") or body.get("workflow_id")
+    workflow_id = body.get("workflow_id")
+    contract_body = {
+        "run_id": run_id,
+        "agent_id": f"workflow:{workflow_id or body.get('name') or 'workflow'}",
+        "runtime": "workflow",
+        "mode": body.get("mode") or "live",
+        "goal": body.get("name") or "workflow",
+        "roles": ["workflow"],
+        "current_role": body.get("current_node") or body.get("paused_node"),
+        "retries": 0,
+        "timeline": list(body.get("timeline") or []),
+        "artifacts": [
+            {
+                "type": "workflow_outputs",
+                "workflow_id": workflow_id,
+                "outputs": body.get("outputs") or {},
+                "pause": body.get("pause") or body.get("pending_approval"),
+            }
+        ],
+        "blocking_reasons": [str((body.get("outputs") or {}).get("error"))] if (body.get("outputs") or {}).get("error") else [],
+        "is_terminal": str(body.get("status") or "") in {"ok", "failed", "cancelled", "interrupted", "partial", "rejected"},
+    }
+    return stamp_contract(
+        contract_body,
+        kind="workflow_run",
+        identity=run_id,
+        status=str(body.get("status") or "unknown"),
+        timestamp=body.get("started_at") or body.get("created_at"),
+    )
+
+
+def audit_event_contract(event: Dict[str, Any]) -> Dict[str, Any]:
+    """Wrap a single audit-log event in the family envelope.
+
+    Audit events have no lifecycle ``status``; we expose the event type as the
+    status so the envelope stays uniform and filterable. Identity is a stable
+    ``event_type@timestamp`` key (audit events are append-only, not addressable).
+    """
+    body = dict(event or {})
+    event_type = str(body.get("event_type") or "event")
+    ts = body.get("timestamp")
+    identity = body.get("event_id") or (f"{event_type}@{ts}" if ts else event_type)
+    contract_body = {
+        "run_id": body.get("run_id"),
+        "agent_id": str(body.get("agent_id") or body.get("workflow_id") or f"audit:{event_type}"),
+        "runtime": "audit",
+        "mode": "event",
+        "goal": event_type,
+        "roles": [],
+        "current_role": None,
+        "retries": int(body.get("retries") or 0),
+        "timeline": [{"event": event_type, "timestamp": ts, "status": body.get("status") or event_type}],
+        "artifacts": [{"type": "audit_payload", "payload": body}],
+        "blocking_reasons": [],
+        "is_terminal": True,
+    }
+    return stamp_contract(
+        contract_body,
+        kind="audit_event",
+        identity=identity,
+        status=event_type,
+        timestamp=ts,
+    )
+
+
+def realtime_event_contract(event: Dict[str, Any]) -> Dict[str, Any]:
+    """Wrap a realtime bus event in the family envelope.
+
+    The bus already assigns a monotonic ``seq`` and ``received_at``; we reuse
+    those as identity and timestamp so the envelope is consistent with the
+    feed's own ordering guarantees.
+    """
+    body = dict(event or {})
+    seq = body.get("seq")
+    payload = body.get("payload") if isinstance(body.get("payload"), dict) else {}
+    contract_body = {
+        "run_id": payload.get("run_id") or body.get("run_id"),
+        "agent_id": str(payload.get("agent_id") or payload.get("workflow_id") or f"realtime:{body.get('area') or 'workspace'}"),
+        "runtime": "realtime",
+        "mode": "event",
+        "goal": str(body.get("event_type") or "event"),
+        "roles": [],
+        "current_role": payload.get("current_role"),
+        "retries": int(payload.get("retries") or 0),
+        "timeline": [{"event": body.get("event_type") or "event", "timestamp": body.get("received_at"), "payload": payload}],
+        "artifacts": [{"type": "realtime_payload", "payload": payload}],
+        "blocking_reasons": [str(payload.get("error"))] if payload.get("error") else [],
+        "is_terminal": str(payload.get("status") or "") in {"ok", "failed", "cancelled", "interrupted", "partial", "rejected"},
+    }
+    return stamp_contract(
+        contract_body,
+        kind="realtime_event",
+        identity=f"rt:{seq}" if seq is not None else None,
+        status=str(body.get("event_type") or "event"),
+        timestamp=body.get("received_at"),
+    )

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 = "7.3.0"
+MULTI_AGENT_VERSION = "7.4.0"
 
 AGENT_ROLES = ("researcher", "planner", "executor", "reviewer", "release")
 CORE_PIPELINE = ("planner", "executor", "reviewer")
@@ -286,6 +286,7 @@ class AgentRunResult:
     retry_history: List[Dict[str, Any]] = field(default_factory=list)
     plan_review: Dict[str, Any] = field(default_factory=dict)
     memory_snapshots: List[Dict[str, Any]] = field(default_factory=list)
+    goal: str = ""
     # "simulation" = deterministic LLM-free runner; "llm" = model-driven (v4 runtime).
     mode: str = "simulation"
 
@@ -306,8 +307,9 @@ class AgentRunResult:
             "retry_history": self.retry_history,
             "plan_review": self.plan_review,
             "memory_snapshots": self.memory_snapshots,
+            "goal": self.goal,
         }
-        payload["contract"] = multi_agent_contract(result=self, goal=self.output)
+        payload["contract"] = multi_agent_contract(result=self, goal=self.goal or self.output)
         return payload
 
 
@@ -800,5 +802,6 @@ class MultiAgentOrchestrator:
             retry_history=ctx.retry_history,
             plan_review=ctx.plan_review,
             memory_snapshots=ctx.memory_snapshots,
+            goal=ctx.goal,
             mode=self.mode,
         )

package/lattice_brain/workflow.py

@@ -27,6 +27,8 @@ from dataclasses import dataclass, field
 from datetime import datetime
 from typing import Any, Callable, Dict, List, Optional
 
+from lattice_brain.runtime.contracts import workflow_run_contract
+
 
 WORKFLOW_ENGINE_VERSION = "2.2.0"
 
@@ -198,7 +200,13 @@ class WorkflowRun:
     paused_context: Optional[Dict[str, Any]] = None
 
     def as_dict(self) -> Dict[str, Any]:
-        return {
+        # Native workflow-run shape is preserved unchanged for existing readers.
+        # A normalized ``agent-run-contract/v1`` projection is attached under
+        # ``contract`` so workflow runs sit in the same observability family as
+        # agent runs, audit events and realtime events (mirrors the audit-log
+        # and realtime-bus convention). The projection is built from the native
+        # dict — never from ``self`` — so it cannot recurse back into as_dict().
+        body = {
             "workflow_id": self.workflow_id,
             "name": self.name,
             "status": self.status,
@@ -211,6 +219,8 @@ class WorkflowRun:
             "pending_approval": self.pending_approval,
             "paused_context": self.paused_context,
         }
+        body["contract"] = workflow_run_contract(body)
+        return body
 
 
 class ApprovalRequired(Exception):

package/latticeai/__init__.py

@@ -1,3 +1,3 @@
 """Lattice AI - modular server package."""
 
-__version__ = "7.3.0"
+__version__ = "7.4.0"

package/latticeai/core/audit.py

@@ -5,9 +5,12 @@ import logging
 import os
 import re
 import threading
+import hashlib
 from pathlib import Path
 from typing import Any, Callable, Dict, List, Optional
 
+from lattice_brain.runtime.contracts import audit_event_contract
+
 from . import timezones
 from .security import redact_secrets
 
@@ -42,12 +45,21 @@ def get_audit_log(audit_file: Path) -> List[Dict]:
 def append_audit_event(audit_file: Path, event_type: str, **payload) -> None:
     try:
         safe_payload = redact_secrets(payload)
+        timestamp = timezones.now_iso()
+        event_hash = hashlib.sha256(
+            json.dumps([event_type, timestamp, safe_payload], ensure_ascii=False, sort_keys=True, default=str).encode("utf-8")
+        ).hexdigest()[:24]
         event = {
+            "event_id": f"audit-{event_hash}",
             "event_type": event_type,
             # item 7: 대시보드 "오늘" 계산과 동일한 시간대 기준으로 기록한다.
-            "timestamp": timezones.now_iso(),
+            "timestamp": timestamp,
             **safe_payload,
         }
+        # Stamp the agent-run-contract/v1 family envelope so audit rows are
+        # uniform with agent/workflow/realtime records. Additive — existing
+        # readers ignore the extra keys; new consumers can filter by family.
+        event["contract"] = audit_event_contract(event)
         with _history_lock:
             events = get_audit_log(audit_file)
             events.append(event)
@@ -236,6 +248,8 @@ def build_admin_audit_report(
 
 def _public_audit_event(event: Dict) -> Dict:
     allowed = {
+        # Stable event id + nested agent-run-contract/v1 family projection.
+        "event_id", "contract",
         "event_type", "timestamp", "role", "user_email", "user_nickname", "source",
         "conversation_id", "workspace_id", "command", "scope", "target_email", "filename", "mime_type",
         "ext", "bytes", "extracted_chars", "graph_node", "keep_last", "removed", "kept",

package/latticeai/core/marketplace.py

@@ -11,7 +11,7 @@ from copy import deepcopy
 from typing import Any, Dict, List, Optional
 
 
-MARKETPLACE_VERSION = "7.3.0"
+MARKETPLACE_VERSION = "7.4.0"
 TEMPLATE_KINDS = ("plugin", "workflow", "agent")
 
 

package/latticeai/core/realtime.py

@@ -32,6 +32,8 @@ import threading
 from datetime import datetime
 from typing import Any, AsyncIterator, Dict, List, Optional, Set
 
+from lattice_brain.runtime.contracts import realtime_event_contract
+
 
 REALTIME_VERSION = "2.2.0"
 _FEED_LIMIT = 200
@@ -99,6 +101,7 @@ class RealtimeBus:
                 "payload": event.get("payload", {}),
                 **{k: v for k, v in event.items() if k not in {"area", "event_type", "workspace_id", "payload"}},
             }
+            enriched["contract"] = realtime_event_contract(enriched)
             self._feed.append(enriched)
             if len(self._feed) > _FEED_LIMIT:
                 self._feed = self._feed[-_FEED_LIMIT:]

package/latticeai/core/workspace_os.py

@@ -18,8 +18,10 @@ from datetime import datetime
 from pathlib import Path
 from typing import Any, Callable, Dict, Iterable, List, Optional
 
+from lattice_brain.runtime.contracts import realtime_event_contract, run_record_contract, workflow_run_contract
 
-WORKSPACE_OS_VERSION = "7.3.0"
+
+WORKSPACE_OS_VERSION = "7.4.0"
 
 # Workspace types separate single-user Personal workspaces from shared
 # Organization workspaces. Both keep the same local-first JSON store; the type
@@ -526,6 +528,7 @@ class WorkspaceOSStore:
             "workspace_id": self._resolve_scope(workspace_id, state),
             "payload": payload,
         }
+        event["contract"] = realtime_event_contract({"seq": event["id"], "received_at": event["timestamp"], **event})
         state.setdefault("timeline", []).append(event)
         self.save_state(state)
         if self.event_sink is not None:
@@ -1565,6 +1568,13 @@ class WorkspaceOSStore:
         if status == "failed":
             self._emit_execution_event(area="agent", event_type="execution_failed", payload={"run_id": run["id"], "agent_id": agent_id, "status": status}, workspace_id=resolved_workspace)
         self.record_timeline_event("agent", "agent_run", {"run_id": run["id"], "agent_id": agent_id, "status": status}, workspace_id=resolved_workspace)
+        run["contract"] = run_record_contract(run)
+        state = self.load_state()
+        for item in _listify(state.get("agent_runs")):
+            if item.get("id") == run["id"]:
+                item["contract"] = run["contract"]
+                break
+        self.save_state(state)
         return run
 
     def update_agent_run(
@@ -1636,6 +1646,13 @@ class WorkspaceOSStore:
                 run["graph_error"] = str(exc)
 
         self.save_state(state)
+        run["contract"] = run_record_contract(run)
+        state = self.load_state()
+        for item in _listify(state.get("agent_runs")):
+            if item.get("id") == run_id:
+                item["contract"] = run["contract"]
+                break
+        self.save_state(state)
 
         timeline = run.get("timeline") or []
         if len(timeline) > old_timeline_len:
@@ -1774,6 +1791,13 @@ class WorkspaceOSStore:
         elif status in {"ok", "partial"}:
             self._emit_execution_event(area="workflow", event_type="workflow_completed", payload={"run_id": run["id"], "workflow_id": workflow_id, "status": status}, workspace_id=resolved_workspace)
         self.record_timeline_event("workflow", "workflow_run", {"run_id": run["id"], "workflow_id": workflow_id, "status": status}, workspace_id=resolved_workspace)
+        run["contract"] = workflow_run_contract(run)
+        state = self.load_state()
+        for item in _listify(state.get("workflow_runs")):
+            if item.get("id") == run["id"]:
+                item["contract"] = run["contract"]
+                break
+        self.save_state(state)
         return run
 
     def update_workflow_run(
@@ -1835,6 +1859,13 @@ class WorkspaceOSStore:
                 run["graph_error"] = str(exc)
 
         self.save_state(state)
+        run["contract"] = workflow_run_contract(run)
+        state = self.load_state()
+        for item in _listify(state.get("workflow_runs")):
+            if item.get("id") == run_id:
+                item["contract"] = run["contract"]
+                break
+        self.save_state(state)
 
         timeline = run.get("timeline") or []
         if len(timeline) > old_timeline_len:
@@ -2053,6 +2084,7 @@ class WorkspaceOSStore:
             "run_id": run_id,
             "status": run.get("status"),
             "workspace_id": self._record_workspace(run),
+            "contract": run.get("contract") or run_record_contract(run),
             "replayable": True,
             "frames": self._replay_frames(run, kind="agent"),
             "handoffs": run.get("handoffs") or [],
@@ -2068,6 +2100,7 @@ class WorkspaceOSStore:
             "run_id": run_id,
             "status": run.get("status"),
             "workspace_id": self._record_workspace(run),
+            "contract": run.get("contract") or workflow_run_contract(run),
             "replayable": True,
             "frames": self._replay_frames(run, kind="workflow"),
             "outputs": run.get("outputs") or {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ltcai",
-  "version": "7.3.0",
+  "version": "7.4.0",
   "description": "Lattice AI — local-first Digital Brain that keeps your knowledge durable across any AI model.",
   "homepage": "https://github.com/TaeSooPark-PTS/LatticeAI#readme",
   "repository": {

package/scripts/brain_quality_eval.py

@@ -12,8 +12,15 @@ import sys
 import tempfile
 from pathlib import Path
 
+REPO_ROOT = Path(__file__).resolve().parents[1]
+if str(REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(REPO_ROOT))
+
+from knowledge_graph import KnowledgeGraphStore
 from lattice_brain.quality import RetrievalBenchmarkRunner
+from latticeai.services.search_service import SearchService
 from latticeai.services.memory_service import MemoryService
+from lattice_brain.retrieval_benchmark_fixtures import DOCUMENTS, FIXTURE_NAME, QUERIES, TOP_K
 
 
 class _EvalStore:
@@ -81,6 +88,37 @@ def _fail(message: str) -> int:
     return 1
 
 
+def _corpus_scale_retrieval_metrics(tmp_path: Path) -> dict:
+    graph = KnowledgeGraphStore(tmp_path / "kg.sqlite", tmp_path / "blobs")
+    id_map = {}
+    for doc in DOCUMENTS:
+        result = graph.ingest_event(
+            doc["type"],
+            f"{doc['title']} {doc['content']}",
+            source="retrieval-benchmark-v740",
+            conversation_id="retrieval-benchmark-v740",
+            metadata={
+                "fixture_id": doc["id"],
+                "title": doc["title"],
+                "content": doc["content"],
+                "workspace_id": "personal",
+            },
+        )
+        id_map[doc["id"]] = result["node_id"]
+    service = SearchService(graph)
+    judged = []
+    for query in QUERIES:
+        payload = service.hybrid_search(query["query"], limit=TOP_K, keyword_limit=TOP_K, vector_limit=TOP_K, graph_limit=TOP_K)
+        retrieved = [item.get("node_id") or item.get("id") for item in payload.get("matches", [])]
+        judged.append({
+            "query": query["query"],
+            "relevant": [id_map[item] for item in query["relevant"]],
+            "must_include": [id_map[item] for item in query.get("must_include", [])],
+            "retrieved": retrieved,
+        })
+    return RetrievalBenchmarkRunner().run_fixture(FIXTURE_NAME, judged, top_k=TOP_K)
+
+
 def main() -> int:
     with tempfile.TemporaryDirectory() as tmp:
         service = MemoryService(
@@ -133,7 +171,18 @@ def main() -> int:
     if retrieval_metrics.get("precision@5", 0.0) < 0.4:
         return _fail(f"hybrid precision regression below threshold: {retrieval_metrics}")
 
-    print(f"brain-quality-eval: OK {retrieval_metrics}")
+    with tempfile.TemporaryDirectory() as tmp:
+        corpus_metrics = _corpus_scale_retrieval_metrics(Path(tmp))
+    if corpus_metrics.get("recall@5", 0.0) < 0.80:
+        return _fail(f"corpus hybrid recall below threshold: {corpus_metrics}")
+    if corpus_metrics.get("precision@5", 0.0) < 0.25:
+        return _fail(f"corpus hybrid precision below threshold: {corpus_metrics}")
+    if corpus_metrics.get("ndcg@5", 0.0) < 0.70:
+        return _fail(f"corpus hybrid ndcg below threshold: {corpus_metrics}")
+    if corpus_metrics.get("must_include_hit_rate", 0.0) < 0.90:
+        return _fail(f"corpus must-include hit rate below threshold: {corpus_metrics}")
+
+    print(f"brain-quality-eval: OK small={retrieval_metrics} corpus={corpus_metrics}")
     return 0
 
 

package/src-tauri/Cargo.lock

@@ -1654,7 +1654,7 @@ dependencies = [
 
 [[package]]
 name = "lattice-ai-desktop"
-version = "7.3.0"
+version = "7.4.0"
 dependencies = [
  "plist",
  "serde",

package/src-tauri/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "lattice-ai-desktop"
-version = "7.3.0"
+version = "7.4.0"
 description = "Lattice AI Digital Brain desktop shell"
 authors = ["TaeSoo Park"]
 edition = "2021"

package/src-tauri/tauri.conf.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://schema.tauri.app/config/2",
   "productName": "Lattice AI",
-  "version": "7.3.0",
+  "version": "7.4.0",
   "identifier": "ai.lattice.desktop",
   "build": {
     "beforeDevCommand": "npm run frontend:dev",

package/static/app/asset-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "7.3.0",
+  "version": "7.4.0",
   "generated_at": "vite",
   "entrypoints": {
     "app": "/static/app/index.html"