ltcai 11.5.0 → 11.5.2

package/scripts/parity_fixture_corpus_docgen.py

@@ -0,0 +1,341 @@
+#!/usr/bin/env python3
+"""The document-generation half of the Python↔Rust parity corpus (v11.5.1).
+
+``scripts/generate_rust_parity_fixtures.py`` owns the store and the goldens;
+this module owns the rows and specs the **document-generation** ports need, so
+neither file has to grow past the tree's file-size ceiling. Nothing here runs
+anything — it is data plus one normalization helper.
+
+Three things are shaped on purpose:
+
+* **Every allow-listed node type appears.** ``search_for_document_generation``
+  admits fifteen types and boosts four of them; a corpus that only carried
+  ``Document`` would prove the boost and the filter equally badly.
+* **The Self-Model subgraph is real.** ``summary_for_prompt`` reads the legacy
+  ``nodes`` table for ``self:%`` ids, so the profile rows are written through
+  the same write door as everything else, including the root the read excludes
+  and a ``self:`` row whose metadata carries no recognised kind (dropped).
+* **``updated_at`` is spread against the frozen clock**, including one stamp
+  that does not parse — the recency term's ``0.0`` branch is otherwise
+  unreachable from a fixture whose every row is well formed.
+
+:func:`normalize_multi_hop` is the one deliberate deviation, and it is a
+*golden* normalization rather than a port divergence: see its docstring.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Tuple
+
+WS_ALPHA = "ws-alpha"
+WS_BETA = "ws-beta"
+
+# ── the document-generation corpus ───────────────────────────────────────────
+# (node_id, type, title, summary, metadata, workspace_id, updated_at)
+DOCGEN_NODES: List[Tuple[str, str, str, str, Dict[str, Any], Optional[str], str]] = [
+    # ── the Self-Model subgraph (read by `summary_for_prompt`) ──────────────
+    # `self:root` is excluded by id, and `self:unknown:*` carries no
+    # `self_model_kind`, so `_row_to_fact` drops it — both are read branches
+    # that only exist if the fixture actually contains them.
+    ("self:root", "Self", "나", "Brain이 사용자에 대해 알고 있는 사실의 뿌리입니다.",
+     {"self_model": True, "self_model_kind": "root"}, None, "2026-07-01T09:00:00"),
+    ("self:decision:a1", "Decision", "문서는 한국어로 쓴다",
+     "문서는 한국어로 쓴다",
+     {"self_model": True, "self_model_kind": "decision", "origin": "user",
+      "confidence": 0.9, "signal": "ko_decision_marker", "workspace_id": WS_ALPHA},
+     WS_ALPHA, "2026-07-02T09:00:00"),
+    ("self:habit:b2", "Habit", "매주 월요일 회의록을 정리한다",
+     "매주 월요일 회의록을 정리한다",
+     {"self_model": True, "self_model_kind": "habit", "origin": "extraction",
+      "confidence": 0.6, "signal": "ko_habit", "workspace_id": None},
+     None, "2026-07-03T09:00:00"),
+    ("self:preference:c3", "Preference", "설명은 짧고 근거를 먼저",
+     "설명은 짧고 근거를 먼저",
+     {"self_model": True, "self_model_kind": "preference", "origin": "user",
+      "confidence": 0.8, "signal": "ko_prefer", "workspace_id": None},
+     None, "2026-07-04T09:00:00"),
+    ("self:relationship:d4", "Relationship", "박민서 님과 빌드 파이프라인을 함께 본다",
+     "박민서 님과 빌드 파이프라인을 함께 본다",
+     {"self_model": True, "self_model_kind": "relationship", "origin": "extraction",
+      "confidence": 0.5, "signal": "ko_with", "workspace_id": WS_BETA},
+     WS_BETA, "2026-07-05T09:00:00"),
+    ("self:trait:e5", "Self", "검색 품질 담당자",
+     "검색 품질 담당자",
+     {"self_model": True, "self_model_kind": "trait", "origin": "user",
+      "confidence": 0.7, "signal": "ko_role", "workspace_id": None},
+     None, "2026-07-06T09:00:00"),
+    ("self:unknown:f6", "Concept", "kind가 없는 self 노드",
+     "self_model_kind가 없어 프로필에서 제외되는 행입니다.",
+     {"self_model": True}, None, "2026-07-07T09:00:00"),
+    # ── the proposal cluster: one hub document with more qualifying
+    #    neighbours than the eight the related-concept join keeps ───────────
+    ("doc:proposal", "Document", "제안서 초안: 검색 품질 개선",
+     "검색 품질 개선 제안서 초안입니다. 근거는 주간 회의 기록과 분기 리뷰 발표자료입니다.",
+     {"relative_path": "docs/proposal.md", "filename": "proposal.md", "ext": ".md"},
+     WS_ALPHA, "2026-07-30T09:00:00"),
+    ("doc:release-notes", "Document", "Release notes for the retrieval port",
+     "Release notes describing the ranking port and the parity harness.",
+     {"source": "release"}, None, "2026-07-28T09:00:00"),
+    ("file:meeting-minutes", "File", "meeting-minutes.md",
+     "회의록: 랭킹 개선과 온보딩 체크리스트를 확정했습니다.",
+     {"filename": "meeting-minutes.md", "relative_path": "notes/meeting-minutes.md"},
+     WS_ALPHA, "2026-08-01T11:00:00"),
+    ("deck:proposal", "SlideDeck", "제안 발표자료",
+     "제안서 초안을 발표용으로 정리한 자료입니다.",
+     {"filename": "proposal.pptx", "ext": ".pptx"}, WS_BETA, "2026-07-29T09:00:00"),
+    ("chat:proposal", "Chat", "제안서 관련 대화",
+     "제안서 초안을 어떻게 쓸지 논의한 대화입니다.",
+     {"conversation_id": "conv-f"}, WS_ALPHA, "2026-07-26T09:00:00"),
+    ("task:proposal-review", "Task", "제안서 검토",
+     "제안서 초안을 검토하고 근거를 확인합니다.", {"status": "open"},
+     WS_ALPHA, "2026-07-27T09:00:00"),
+    ("dec:doc-format", "Decision", "문서 형식은 마크다운으로 통일",
+     "문서 생성 결과는 마크다운으로 통일하기로 했습니다.", {},
+     WS_ALPHA, "2026-07-22T09:00:00"),
+    ("feature:doc-generation", "Feature", "문서 생성",
+     "질문에서 문서를 만들어 주는 기능입니다.", {}, WS_ALPHA, "2026-07-25T09:00:00"),
+    ("concept:proposal", "Concept", "제안서",
+     "제안서는 결정을 요청하는 문서입니다.", {}, None, "2026-07-24T09:00:00"),
+    ("concept:evidence", "Concept", "근거",
+     "근거는 주장을 뒷받침하는 자료입니다.", {}, WS_ALPHA, "2026-07-23T09:00:00"),
+    ("page:proposal-outline", "Page", "제안서 목차",
+     "제안서 목차 페이지입니다.", {}, None, "2026-07-21T09:00:00"),
+    ("slide:proposal-1", "Slide", "제안 슬라이드 1",
+     "제안서 요약 슬라이드입니다.", {}, WS_BETA, "2026-07-19T09:00:00"),
+    ("sheet:proposal-budget", "Spreadsheet", "proposal-budget.xlsx",
+     "제안서 예산 표입니다.", {"filename": "proposal-budget.xlsx", "ext": ".xlsx"},
+     WS_ALPHA, "2026-07-17T09:00:00"),
+    ("img:proposal-sketch", "Image", "proposal-sketch.png",
+     "제안서 구조 스케치입니다.", {"filename": "proposal-sketch.png", "ext": ".png"},
+     WS_BETA, "2026-07-16T09:00:00"),
+    ("imgtext:proposal-ocr", "ImageText", "제안서 스케치 OCR",
+     "제안서 구조: 배경, 근거, 결론.",
+     {"filename": "proposal-sketch.png", "ocr": True}, WS_BETA, "2026-07-16T09:01:00"),
+    ("audio:proposal-call", "Audio", "proposal-call.m4a",
+     "제안서 관련 통화 녹음입니다.", {"filename": "proposal-call.m4a", "ext": ".m4a"},
+     WS_ALPHA, "2026-07-15T09:00:00"),
+    ("code:doc-builder", "CodeFile", "context_builder.py",
+     "문서 생성 컨텍스트를 조합하는 코드입니다. 제안서 생성도 여기를 지납니다.",
+     {"filename": "context_builder.py",
+      "relative_path": "latticeai/core/context_builder.py"},
+     WS_ALPHA, "2026-07-14T09:00:00"),
+    # The recency term's `0.0` branch: a stamp `datetime.fromisoformat` refuses.
+    ("doc:undated", "Document", "Undated 제안서 memo",
+     "An undated memo about 제안서; its stamp does not parse.", {},
+     None, "not-a-timestamp"),
+]
+
+# (from, to, type, weight, created_at) — appended to the base edge set.
+DOCGEN_EDGES: List[Tuple[str, str, str, float, str]] = [
+    ("doc:proposal", "concept:proposal", "mentions", 0.92, "2026-07-30T00:00:00"),
+    ("doc:proposal", "concept:evidence", "mentions", 0.91, "2026-07-30T00:01:00"),
+    ("doc:proposal", "feature:doc-generation", "relates_to", 0.90, "2026-07-30T00:02:00"),
+    ("doc:proposal", "dec:doc-format", "relates_to", 0.89, "2026-07-30T00:03:00"),
+    ("doc:proposal", "task:proposal-review", "relates_to", 0.88, "2026-07-30T00:04:00"),
+    ("doc:proposal", "concept:retrieval", "mentions", 0.87, "2026-07-30T00:05:00"),
+    ("doc:proposal", "concept:ranking", "mentions", 0.86, "2026-07-30T00:06:00"),
+    ("doc:proposal", "feature:command-palette", "mentions", 0.85, "2026-07-30T00:07:00"),
+    ("doc:proposal", "task:parity-harness", "relates_to", 0.84, "2026-07-30T00:08:00"),
+    ("doc:proposal", "page:proposal-outline", "contains", 0.83, "2026-07-30T00:09:00"),
+    ("deck:proposal", "doc:proposal", "relates_to", 0.82, "2026-07-29T00:00:00"),
+    ("deck:proposal", "slide:proposal-1", "contains", 0.81, "2026-07-29T00:01:00"),
+    ("file:meeting-minutes", "dec:doc-format", "relates_to", 0.80, "2026-07-28T00:00:00"),
+    ("file:meeting-minutes", "meeting:weekly", "relates_to", 0.79, "2026-07-28T00:01:00"),
+    ("chat:proposal", "doc:proposal", "mentions", 0.78, "2026-07-27T00:00:00"),
+    ("img:proposal-sketch", "imgtext:proposal-ocr", "relates_to", 0.77, "2026-07-26T00:00:00"),
+    ("imgtext:proposal-ocr", "concept:proposal", "mentions", 0.76, "2026-07-26T00:01:00"),
+    ("audio:proposal-call", "task:proposal-review", "mentions", 0.75, "2026-07-25T00:00:00"),
+    ("code:doc-builder", "feature:doc-generation", "relates_to", 0.74, "2026-07-24T00:00:00"),
+    ("sheet:proposal-budget", "doc:proposal", "relates_to", 0.73, "2026-07-23T00:00:00"),
+    ("doc:release-notes", "concept:ranking", "mentions", 0.72, "2026-07-22T00:00:00"),
+    ("doc:undated", "concept:proposal", "mentions", 0.71, "2026-07-21T00:00:00"),
+    # The Self-Model's own shape: every fact points at the root.
+    ("self:decision:a1", "self:root", "PART_OF", 1.0, "2026-07-02T00:00:00"),
+    ("self:habit:b2", "self:root", "PART_OF", 1.0, "2026-07-03T00:00:00"),
+    ("self:preference:c3", "self:root", "PART_OF", 1.0, "2026-07-04T00:00:00"),
+    ("self:relationship:d4", "self:root", "PART_OF", 1.0, "2026-07-05T00:00:00"),
+    ("self:trait:e5", "self:root", "PART_OF", 1.0, "2026-07-06T00:00:00"),
+    ("self:unknown:f6", "self:root", "PART_OF", 1.0, "2026-07-07T00:00:00"),
+]
+
+# ── suite specs ──────────────────────────────────────────────────────────────
+DOCGEN_SEARCH_SPECS: List[Dict[str, Any]] = [
+    {"key": "ko_proposal", "query": "제안서 초안"},
+    {"key": "ko_meeting", "query": "회의 결정 사항"},
+    {"key": "en_ranking", "query": "hybrid retrieval ranking"},
+    {"key": "ko_sketch", "query": "스케치"},
+    {"key": "ko_self_model", "query": "문서는 한국어로"},
+    {"key": "en_undated", "query": "Undated"},
+    {"key": "hub_deck", "query": "제안 발표자료"},
+    {"key": "tie", "query": "Tie candidate"},
+    {"key": "no_hit", "query": "zzqq wumpus nonsense"},
+    {"key": "empty_query", "query": ""},
+    {"key": "blank_query", "query": "   "},
+    {"key": "limit_one", "query": "제안서", "limit": 1},
+    {"key": "limit_zero", "query": "제안서", "limit": 0},
+    {"key": "limit_over", "query": "제안서", "limit": 900},
+    {"key": "scoped_alpha", "query": "제안서", "allowed": [WS_ALPHA]},
+    {"key": "scoped_alpha_legacy", "query": "제안서", "allowed": [WS_ALPHA], "legacy": True},
+    {"key": "scoped_beta", "query": "제안서", "allowed": [WS_BETA]},
+    {"key": "scoped_empty", "query": "제안서", "allowed": []},
+]
+
+MULTI_HOP_SPECS: List[Dict[str, Any]] = [
+    *[{"key": f"hub_h{hops}", "node_ids": ["doc:proposal"], "max_hops": hops}
+      for hops in (0, 1, 2, 3)],
+    {"key": "hub_hneg", "node_ids": ["doc:proposal"], "max_hops": -1},
+    {"key": "multi_seed", "node_ids": ["doc:proposal", "dec:fusion-alpha"], "max_hops": 2},
+    {"key": "leaf", "node_ids": ["slide:proposal-1"], "max_hops": 2},
+    {"key": "isolated", "node_ids": ["tie:c"], "max_hops": 2},
+    {"key": "self_root", "node_ids": ["self:root"], "max_hops": 2},
+    {"key": "missing_seed", "node_ids": ["nope:missing"], "max_hops": 2},
+    {"key": "no_seeds", "node_ids": [], "max_hops": 2},
+    {"key": "scoped_alpha", "node_ids": ["doc:proposal"], "max_hops": 2,
+     "allowed": [WS_ALPHA]},
+    {"key": "scoped_alpha_legacy", "node_ids": ["doc:proposal"], "max_hops": 2,
+     "allowed": [WS_ALPHA], "legacy": True},
+    {"key": "scoped_beta", "node_ids": ["deck:proposal"], "max_hops": 2,
+     "allowed": [WS_BETA]},
+    {"key": "scoped_empty", "node_ids": ["doc:proposal"], "max_hops": 2, "allowed": []},
+]
+
+CONTEXT_DOCUMENT_SPECS: List[Dict[str, Any]] = [
+    {"key": "default", "query": "제안서 초안"},
+    {"key": "no_self_model", "query": "제안서 초안", "include_self_model": False},
+    {"key": "self_model_tokens_small", "query": "제안서 초안", "self_model_tokens": 12},
+    {"key": "budget_240", "query": "제안서 초안", "budget": 240},
+    {"key": "budget_120", "query": "제안서 초안", "budget": 120},
+    {"key": "budget_40", "query": "제안서 초안", "budget": 40},
+    {"key": "budget_one", "query": "제안서 초안", "budget": 1},
+    {"key": "budget_zero", "query": "제안서 초안", "budget": 0},
+    {"key": "hops_zero", "query": "제안서 초안", "max_hops": 0},
+    {"key": "hops_three", "query": "제안서 초안", "max_hops": 3},
+    {"key": "results_two", "query": "제안서 초안", "max_results": 2},
+    {"key": "ko_meeting", "query": "회의 결정 사항"},
+    {"key": "en_ranking", "query": "hybrid retrieval ranking"},
+    {"key": "ko_sketch", "query": "스케치"},
+    {"key": "fallback_lexical", "query": "박민서 님"},
+    {"key": "fallback_empty", "query": "zzqq wumpus nonsense"},
+    {"key": "empty_query", "query": ""},
+    {"key": "scoped_alpha", "query": "제안서 초안", "allowed": [WS_ALPHA]},
+    {"key": "scoped_alpha_legacy", "query": "제안서 초안", "allowed": [WS_ALPHA],
+     "legacy": True},
+    {"key": "scoped_empty", "query": "제안서 초안", "allowed": []},
+]
+
+
+def normalize_multi_hop(payload: Dict[str, Any]) -> Dict[str, Any]:
+    """Order a ``multi_hop_context`` answer deterministically.
+
+    **This is a golden normalization, not a port divergence.** Python's
+    traversal iterates ``frontier``, a ``set`` — so the order in which the
+    nodes of one hop are appended (and therefore the order their incident
+    edges are appended) depends on string hashing, which CPython randomizes
+    per process unless ``PYTHONHASHSEED`` is pinned. The *contents* are fully
+    determined (which nodes are visited, which edges are collected, and every
+    node's hop label); only the sequence is not, so the live response ordering
+    is unspecified and there is nothing for a port to reproduce.
+
+    Both sides therefore sort before comparing: nodes by ``(hop, id)``, edges
+    by ``(from, to, type, weight)``. The Rust port emits that order natively —
+    it is deterministic where Python is not, which is a strictly stronger
+    promise and not a different answer.
+    """
+    return {
+        "nodes": sorted(payload["nodes"], key=lambda node: (node["hop"], node["id"])),
+        "edges": sorted(
+            payload["edges"],
+            key=lambda edge: (edge["from"], edge["to"], edge["type"], edge["weight"]),
+        ),
+    }
+
+
+class OrderedMultiHopStore:
+    """The store, with ``multi_hop_context`` ordered deterministically.
+
+    ``retrieve_context_for_generation`` feeds the traversal's node list into
+    ``extra_nodes``, and the concept section renders the first eight of it — so
+    Python's unordered ``frontier`` iteration reaches the *rendered markdown*,
+    not only the traversal payload. Both sides therefore see the normalized
+    order (see :func:`normalize_multi_hop`); every other attribute is forwarded
+    to the real store untouched.
+    """
+
+    def __init__(self, store: Any):
+        self._store = store
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._store, name)
+
+    def multi_hop_context(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
+        return normalize_multi_hop(self._store.multi_hop_context(*args, **kwargs))
+
+
+def _scope(spec: Dict[str, Any]) -> Dict[str, Any]:
+    """The graph-layer scope every document-generation read takes."""
+    allowed = spec.get("allowed")
+    return {
+        "allowed_workspaces": None if allowed is None else set(allowed),
+        "include_legacy_global": spec.get("legacy", False),
+    }
+
+
+def run_docgen_search(harness: Any, spec: Dict[str, Any]) -> List[Dict[str, Any]]:
+    """``KnowledgeGraphStore.search_for_document_generation`` for one spec."""
+    return harness.store.search_for_document_generation(
+        spec["query"], limit=spec.get("limit", 10), **_scope(spec)
+    )
+
+
+def run_multi_hop(harness: Any, spec: Dict[str, Any]) -> Dict[str, Any]:
+    """``multi_hop_context`` for one spec, in the normalized order."""
+    return normalize_multi_hop(
+        harness.store.multi_hop_context(
+            spec["node_ids"], max_hops=spec.get("max_hops", 2), **_scope(spec)
+        )
+    )
+
+
+def run_context_document(harness: Any, spec: Dict[str, Any]) -> Dict[str, Any]:
+    """``retrieve_context_for_generation`` plus the footnote over its sources.
+
+    The footnote is a second public entry point over the same ``sources`` list;
+    carrying it here proves that port too, without a suite of its own.
+    """
+    from lattice_brain.self_model import DEFAULT_SUMMARY_TOKENS
+    from latticeai.core.context_builder import (
+        DEFAULT_DOCUMENT_CONTEXT_BUDGET,
+        format_sources_footnote,
+        retrieve_context_for_generation,
+    )
+
+    context = retrieve_context_for_generation(
+        OrderedMultiHopStore(harness.store),
+        spec["query"],
+        max_results=spec.get("max_results", 10),
+        max_hops=spec.get("max_hops", 2),
+        budget=spec.get("budget", DEFAULT_DOCUMENT_CONTEXT_BUDGET),
+        include_self_model=spec.get("include_self_model", True),
+        self_model_tokens=spec.get("self_model_tokens", DEFAULT_SUMMARY_TOKENS),
+        **_scope(spec),
+    )
+    return {
+        "context": context,
+        "sources_footnote": format_sources_footnote(context["sources"]),
+    }
+
+
+#: The three document-generation suites, as the generator merges them into
+#: :data:`SUITES` / :data:`SUITE_RUNNERS`. Keeping the pair side by side is what
+#: stops a spec list from arriving without the runner that answers it.
+DOCGEN_SUITES: Dict[str, List[Dict[str, Any]]] = {
+    "docgen_search": DOCGEN_SEARCH_SPECS,
+    "multi_hop": MULTI_HOP_SPECS,
+    "context_document": CONTEXT_DOCUMENT_SPECS,
+}
+
+DOCGEN_RUNNERS: Dict[str, Any] = {
+    "docgen_search": run_docgen_search,
+    "multi_hop": run_multi_hop,
+    "context_document": run_context_document,
+}

package/scripts/release_screen_claims.json

@@ -21,6 +21,26 @@
     "specific, not less."
   ],
 
+  "11.5.2": {
+    "_why": [
+      "Tight Ship release: deletions, consolidation and front-door fixes —",
+      "backend only. The frontend bundle is untouched; no captured screen",
+      "changes on purpose. All thirteen measured but not gated. Known",
+      "jitter: 05-memory-graph moves ~2-3% between captures from the",
+      "cytoscape layout (11.3.0-11.5.1 observed)."
+    ]
+  },
+
+  "11.5.1": {
+    "_why": [
+      "Rust Full Loop release: agent-loop orchestrator port, worker seams,",
+      "doc-gen context builder — backend only. The frontend bundle is",
+      "untouched; no captured screen changes on purpose. All thirteen",
+      "measured but not gated. Known jitter: 05-memory-graph moves ~2-3%",
+      "between captures from the cytoscape layout (11.3.0-11.5.0 observed)."
+    ]
+  },
+
   "11.5.0": {
     "_why": [
       "Rust Complete release: backend/desktop-topology architecture only",

package/src-tauri/Cargo.lock

@@ -1730,17 +1730,23 @@ dependencies = [
 
 [[package]]
 name = "lattice-agent"
-version = "11.5.0"
+version = "11.5.2"
 dependencies = [
  "axum",
+ "base64 0.22.1",
+ "fancy-regex",
+ "futures-core",
+ "getrandom 0.4.3",
+ "reqwest 0.12.28",
  "serde",
  "serde_json",
+ "sha2",
  "tokio",
 ]
 
 [[package]]
 name = "lattice-ai-desktop"
-version = "11.5.0"
+version = "11.5.2"
 dependencies = [
  "lattice-host",
  "lattice-jobs",
@@ -1755,7 +1761,7 @@ dependencies = [
 
 [[package]]
 name = "lattice-core"
-version = "11.5.0"
+version = "11.5.2"
 dependencies = [
  "blake2",
  "rusqlite",
@@ -1765,7 +1771,7 @@ dependencies = [
 
 [[package]]
 name = "lattice-host"
-version = "11.5.0"
+version = "11.5.2"
 dependencies = [
  "axum",
  "lattice-agent",
@@ -1782,7 +1788,7 @@ dependencies = [
 
 [[package]]
 name = "lattice-ingest"
-version = "11.5.0"
+version = "11.5.2"
 dependencies = [
  "axum",
  "lattice-core",
@@ -1795,7 +1801,7 @@ dependencies = [
 
 [[package]]
 name = "lattice-jobs"
-version = "11.5.0"
+version = "11.5.2"
 dependencies = [
  "axum",
  "lattice-core",
@@ -1807,7 +1813,7 @@ dependencies = [
 
 [[package]]
 name = "lattice-retrieval"
-version = "11.5.0"
+version = "11.5.2"
 dependencies = [
  "axum",
  "fancy-regex",

package/src-tauri/Cargo.toml

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

package/src-tauri/src/backend.rs

@@ -72,6 +72,9 @@ pub struct BackendStatus {
     /// Whether the background jobs timer is running in this process
     /// (11.5.0, additive).
     pub jobs_running: bool,
+    /// Why the front door is not there, when this shell was supposed to serve
+    /// one and could not bind it (11.5.2, additive). `null` normally.
+    pub gateway_error: Option<String>,
 }
 
 /// The gateway this shell is serving, and how to stop it.
@@ -89,6 +92,11 @@ pub struct DesktopBackend {
     gateway: Mutex<Option<RunningGateway>>,
     /// The jobs scheduler, mounted on `/host/jobs` in the gateway topology.
     jobs: Option<Arc<lattice_jobs::Scheduler>>,
+    /// Why the front door is not there, when it could not be bound.
+    ///
+    /// `None` means "nothing went wrong" — including in the topologies that
+    /// serve no gateway at all, where the worker *is* the front door.
+    gateway_error: Mutex<Option<String>>,
 }
 
 impl DesktopBackend {
@@ -116,6 +124,7 @@ impl DesktopBackend {
             health_deadline,
             gateway: Mutex::new(None),
             jobs,
+            gateway_error: Mutex::new(None),
         })
     }
 
@@ -139,6 +148,18 @@ impl DesktopBackend {
         self.plan.topology
     }
 
+    /// Why the front door is unavailable, when it is.
+    ///
+    /// `Some` only when this shell was supposed to serve the gateway and could
+    /// not bind it — in which case [`Self::app_url`] names a port nothing will
+    /// ever listen on, and `main::boot` must not navigate the window into it.
+    pub fn gateway_error(&self) -> Option<String> {
+        self.gateway_error
+            .lock()
+            .expect("gateway error lock")
+            .clone()
+    }
+
     /// Start the front door, then the worker.
     ///
     /// The gateway comes up first on purpose: it is what the webview polls, and
@@ -171,10 +192,16 @@ impl DesktopBackend {
         let listener = match bind_loopback(addr).await {
             Ok(listener) => listener,
             Err(err) => {
-                eprintln!(
-                    "lattice-ai-desktop: the gateway could not bind {addr}: {err} — \
+                let message = format!(
+                    "the gateway could not bind {addr}: {err} — \
                      set LATTICEAI_DESKTOP_DIRECT=1 to run the worker as the front door"
                 );
+                eprintln!("lattice-ai-desktop: {message}");
+                // Recorded, not only logged: `plan.origin` names the port that
+                // just failed to bind, so navigating the window there would
+                // land on a connection refused with no explanation. The window
+                // stays on the bundled shell and reads this instead.
+                *self.gateway_error.lock().expect("gateway error lock") = Some(message);
                 return;
             }
         };
@@ -310,6 +337,7 @@ impl DesktopBackend {
                 .as_ref()
                 .map(|scheduler| scheduler.is_running())
                 .unwrap_or(false),
+            gateway_error: self.gateway_error(),
         }
     }
 
@@ -457,4 +485,50 @@ mod tests {
         shell.stop_gateway();
         shell.stop_gateway();
     }
+
+    /// A shell that never had to bind a front door has nothing to report, and
+    /// its origin is navigable.
+    #[test]
+    fn a_healthy_shell_names_no_gateway_error() {
+        for probe in [
+            StaticProbe::new().with_env(PORT_ENV, "41844"),
+            StaticProbe::new().with_env(DIRECT_ENV, "1"),
+        ] {
+            let shell = backend(probe);
+            assert_eq!(shell.gateway_error(), None);
+            let value =
+                serde_json::to_value(shell.render(&WorkerStatus::idle(4825, true))).expect("json");
+            assert!(value["gateway_error"].is_null());
+        }
+    }
+
+    /// Binding the front door is the one failure that makes `app_url` name a
+    /// port nothing will ever answer on. The window must read the reason rather
+    /// than navigate into it.
+    #[tokio::test]
+    async fn a_gateway_that_cannot_bind_is_reported_and_not_navigated_to() {
+        // Hold the port the shell will try to bind.
+        let occupied = std::net::TcpListener::bind("127.0.0.1:0").expect("bind");
+        let port = occupied.local_addr().expect("addr").port();
+        let shell = backend(StaticProbe::new().with_env(PORT_ENV, &port.to_string()));
+        assert_eq!(shell.topology(), Topology::Gateway);
+
+        shell.start_gateway().await;
+
+        let reason = shell.gateway_error().expect("the failure is recorded");
+        assert!(reason.contains("could not bind"), "{reason}");
+        assert!(
+            reason.contains("LATTICEAI_DESKTOP_DIRECT"),
+            "the way out is named: {reason}"
+        );
+        assert!(
+            shell.app_url().contains(&port.to_string()),
+            "app_url still names the port nothing bound — which is why boot must \
+             read gateway_error instead of navigating"
+        );
+        let value =
+            serde_json::to_value(shell.render(&WorkerStatus::idle(port, true))).expect("serialise");
+        assert_eq!(value["gateway_error"], reason);
+        drop(occupied);
+    }
 }

package/src-tauri/src/main.rs

@@ -82,9 +82,19 @@ fn boot(app: &tauri::App) {
             // Waiting in both places would double the worst case.
             shell.wait_until_serving().await;
         }
-        // Navigate either way, as the shell always has: a window showing the
-        // browser's own "cannot connect" is more use than a window showing
-        // nothing while a worker that will never arrive is waited for.
+        // One reason not to navigate, and it is not "the worker is slow": if
+        // this shell was supposed to serve the front door and could not bind
+        // it, `app_url` names a port nothing will ever listen on, and sending
+        // the window there replaces a readable failure with a blank "cannot
+        // connect". The bundled shell stays up and reads `gateway_error` out of
+        // `desktopBackendStatus` instead.
+        if let Some(reason) = shell.gateway_error() {
+            eprintln!("lattice-ai-desktop: staying on the bundled shell — {reason}");
+            return;
+        }
+        // Otherwise navigate either way, as the shell always has: a window
+        // showing the browser's own "cannot connect" is more use than a window
+        // showing nothing while a worker that will never arrive is waited for.
         if let Ok(url) = tauri::Url::parse(&shell.app_url()) {
             let _ = window.navigate(url);
         }

package/src-tauri/tauri.conf.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://schema.tauri.app/config/2",
   "productName": "Lattice AI",
-  "version": "11.5.0",
+  "version": "11.5.2",
   "identifier": "ai.lattice.desktop",
   "build": {
     "beforeDevCommand": "npm run frontend:dev",
@@ -22,7 +22,7 @@
       }
     ],
     "security": {
-      "csp": "default-src 'self' asset: tauri: http://127.0.0.1:*; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' asset: data: blob: http://127.0.0.1:*; font-src 'self' data:; connect-src 'self' ipc: http://127.0.0.1:* ws://127.0.0.1:*; frame-src 'none'; object-src 'none'; base-uri 'none'; form-action 'self'",
+      "csp": "default-src 'self' asset: tauri: http://127.0.0.1:*; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' asset: data: blob: http://127.0.0.1:*; font-src 'self' data:; connect-src 'self' ipc: http://127.0.0.1:*; frame-src 'none'; object-src 'none'; base-uri 'none'; form-action 'self'",
       "devCsp": "default-src 'self' http://127.0.0.1:* ws://127.0.0.1:*; script-src 'self' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob: http://127.0.0.1:*; font-src 'self' data:; connect-src 'self' http://127.0.0.1:* ws://127.0.0.1:*; frame-src 'none'; object-src 'none'; base-uri 'none'; form-action 'self'"
     }
   },